Author: chirino
Date: Thu Dec 28 13:28:11 2006
New Revision: 490830
URL: http://svn.apache.org/viewvc?view=rev&rev=490830
Log:
Latest export from confluence
Modified:
incubator/activemq/site/openwire.html
Modified: incubator/activemq/site/openwire.html
URL:
http://svn.apache.org/viewvc/incubator/activemq/site/openwire.html?view=diff&rev=490830&r1=490829&r2=490830
==============================================================================
--- incubator/activemq/site/openwire.html (original)
+++ incubator/activemq/site/openwire.html Thu Dec 28 13:28:11 2006
@@ -270,18 +270,6 @@
<P>So OpenWire automates the creation of language specific <A
href="wire-protocol.html" title="Wire Protocol">Wire Protocol</A>
implementations; then its a matter of wrapping the language specific TCP/IP
socket code and wrapping the API in some easy to use functions/classes.</P>
-<H3><A name="OpenWire-CoreIOprimitives"></A>Core IO primitives</H3>
-
-<P>Each command gets marshalled to and from the wire using a code generated
marshaller for the language in question (Java, C#, C, Ruby etc). The core IO
primitives are as follows</P>
-<UL>
- <LI>read/write String: ideally would use read/writeUTF format from
Java's DataIn/Out interfaces; but could just use double byte character
format</LI>
- <LI>read/write byte, short, long - using Java's endian</LI>
- <LI>read/write Destinations. See below for how those are sent.</LI>
- <LI>read/write properties: this uses Java syntax for properties; each
line contains a key/value pair separated by '='.</LI>
- <LI>read/write bytes: done by writing an int for the length followed by
the number of bytes.</LI>
-</UL>
-
-
<H3><A name="OpenWire-Specification"></A>Specification</H3>
<H4><A name="OpenWire-Overview"></A>Overview</H4>
@@ -312,12 +300,12 @@
<H4><A name="OpenWire-WireFormatNegotiation"></A>Wire Format Negotiation</H4>
-<P>OpenWire is an extensible in that it supports adding new encoding options
while still being backward compatible with previous versions of the protocol.
Every OpenWire protocol session initially starts with all encoding options
turned off and at version 1 of command marshalers. An initial WireFormatInfo
command is exchanged between the two nodes so that additional encoding features
can be enabled. If both sides request an encoding feature to be enabled then
it will be enabled. The command marshalers used will be the highest version
that they both support.</P>
+<P>OpenWire is an extensible in that it supports adding new encoding options
while still being backward compatible with previous versions of the protocol.
Every OpenWire protocol session initially starts with all encoding options
turned off and at version 1 of command marshalers. An initial WIREFORMAT_INFO
command is exchanged between the two nodes so that additional encoding features
can be enabled. If both sides request an encoding feature to be enabled then
it will be enabled. The command marshalers used will be the highest version
that they both support.</P>
<DIV class="code"><DIV class="codeContent">
-<PRE class="code-java">+------------------------+ +---------+ +---------+
+---------+
-| WireFormatInfo command | | command | | command | .... | command |
-+------------------------+ +---------+ +---------+ +---------+</PRE>
+<PRE class="code-java">+-------------------------+ +---------+ +---------+
+---------+
+| WIREFORMAT_INFO command | | command | | command | .... | command |
++-------------------------+ +---------+ +---------+ +---------+</PRE>
</DIV></DIV>
<H4><A name="OpenWire-CommandEncoding"></A>Command Encoding</H4>
@@ -331,7 +319,7 @@
[ +------+ ] +------+-------------------------+
[ | size | ] | type | command-specific-fields |
[ +------+ ] +------+-------------------------+
-[ | <SPAN class="code-object">int</SPAN> | ] | <SPAN
class="code-object">byte</SPAN> | (size-1) bytes |
+[ | <SPAN class="code-object">int</SPAN> | ] | <SPAN
class="code-object">byte</SPAN> | (size-1) octects |
[ +------+ ] +------+-------------------------+
[========================]</PRE>
</DIV></DIV>
@@ -357,7 +345,333 @@
<P>If a command type does not have any command specific content, then size
would be 1.</P>
-<P>Prefixing the size on every command is done to aid in non-blocking IO
processing so that receiver can easily determine when a whole command has been
received and can be processed. But finding out the size of command takes
additional buffering on the sender size and is not needed if the receiver is
doing blocking IO. If the SizePrefixDisabled option is enabled after the
exchange of WireFormatInfo packets, then every subsequent command will not have
the size prefixed.</P>
+<P>Prefixing the size on every command is done to aid in non-blocking IO
processing so that receiver can easily determine when a whole command has been
received and can be processed. But finding out the size of command takes
additional buffering on the sender size and is not needed if the receiver is
doing blocking IO. If the SizePrefixDisabled option is enabled after the
exchange of WIREFORMAT_INFO packets, then every subsequent command will not
have the size prefixed.</P>
+
+
+<H4><A name="OpenWire-CommandTypes"></A>Command Types</H4>
+
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> Type Identifier </TH>
+<TH class="confluenceTh"> Command </TH>
+<TH class="confluenceTh"> Description </TH>
+</TR>
+<TR>
+<TD class="confluenceTd">1</TD>
+<TD class="confluenceTd">WIREFORMAT_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">2</TD>
+<TD class="confluenceTd">BROKER_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">3</TD>
+<TD class="confluenceTd">CONNECTION_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">4</TD>
+<TD class="confluenceTd">SESSION_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">5</TD>
+<TD class="confluenceTd">CONSUMER_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">6</TD>
+<TD class="confluenceTd">PRODUCER_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">7</TD>
+<TD class="confluenceTd">TRANSACTION_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">8</TD>
+<TD class="confluenceTd">DESTINATION_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">9</TD>
+<TD class="confluenceTd">REMOVE_SUBSCRIPTION_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">10</TD>
+<TD class="confluenceTd">KEEP_ALIVE_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">11</TD>
+<TD class="confluenceTd">SHUTDOWN_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">12</TD>
+<TD class="confluenceTd">REMOVE_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">14</TD>
+<TD class="confluenceTd">CONTROL_COMMAND </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">15</TD>
+<TD class="confluenceTd">FLUSH_COMMAND </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">16</TD>
+<TD class="confluenceTd">CONNECTION_ERROR </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">17</TD>
+<TD class="confluenceTd">CONSUMER_CONTROL </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">18</TD>
+<TD class="confluenceTd">CONNECTION_CONTROL </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">21</TD>
+<TD class="confluenceTd">MESSAGE_DISPATCH </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">22</TD>
+<TD class="confluenceTd">MESSAGE_ACK </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">23</TD>
+<TD class="confluenceTd">ACTIVEMQ_MESSAGE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">24</TD>
+<TD class="confluenceTd">ACTIVEMQ_BYTES_MESSAGE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">25</TD>
+<TD class="confluenceTd">ACTIVEMQ_MAP_MESSAGE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">26</TD>
+<TD class="confluenceTd">ACTIVEMQ_OBJECT_MESSAGE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">27</TD>
+<TD class="confluenceTd">ACTIVEMQ_STREAM_MESSAGE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">28</TD>
+<TD class="confluenceTd">ACTIVEMQ_TEXT_MESSAGE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">30</TD>
+<TD class="confluenceTd">RESPONSE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">31</TD>
+<TD class="confluenceTd">EXCEPTION_RESPONSE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">32</TD>
+<TD class="confluenceTd">DATA_RESPONSE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">33</TD>
+<TD class="confluenceTd">DATA_ARRAY_RESPONSE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">34</TD>
+<TD class="confluenceTd">INTEGER_RESPONSE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">40</TD>
+<TD class="confluenceTd">DISCOVERY_EVENT </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">50</TD>
+<TD class="confluenceTd">JOURNAL_ACK </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">52</TD>
+<TD class="confluenceTd">JOURNAL_REMOVE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">53</TD>
+<TD class="confluenceTd">JOURNAL_TRACE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">54</TD>
+<TD class="confluenceTd">JOURNAL_TRANSACTION </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">55</TD>
+<TD class="confluenceTd">DURABLE_SUBSCRIPTION_INFO </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">60</TD>
+<TD class="confluenceTd">PARTIAL_COMMAND </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">61</TD>
+<TD class="confluenceTd">PARTIAL_LAST_COMMAND </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">65</TD>
+<TD class="confluenceTd">REPLAY </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">70</TD>
+<TD class="confluenceTd">BYTE_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">71</TD>
+<TD class="confluenceTd">CHAR_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">72</TD>
+<TD class="confluenceTd">SHORT_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">73</TD>
+<TD class="confluenceTd">INTEGER_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">74</TD>
+<TD class="confluenceTd">LONG_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">75</TD>
+<TD class="confluenceTd">DOUBLE_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">76</TD>
+<TD class="confluenceTd">FLOAT_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">77</TD>
+<TD class="confluenceTd">STRING_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">78</TD>
+<TD class="confluenceTd">BOOLEAN_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">79</TD>
+<TD class="confluenceTd">BYTE_ARRAY_TYPE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">90</TD>
+<TD class="confluenceTd">MESSAGE_DISPATCH_NOTIFICATION </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">91</TD>
+<TD class="confluenceTd">NETWORK_BRIDGE_FILTER </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">100</TD>
+<TD class="confluenceTd">ACTIVEMQ_QUEUE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">101</TD>
+<TD class="confluenceTd">ACTIVEMQ_TOPIC </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">102</TD>
+<TD class="confluenceTd">ACTIVEMQ_TEMP_QUEUE </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">103</TD>
+<TD class="confluenceTd">ACTIVEMQ_TEMP_TOPIC </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">110</TD>
+<TD class="confluenceTd">MESSAGE_ID </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">111</TD>
+<TD class="confluenceTd">ACTIVEMQ_LOCAL_TRANSACTION_ID </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">112</TD>
+<TD class="confluenceTd">ACTIVEMQ_XA_TRANSACTION_ID </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">120</TD>
+<TD class="confluenceTd">CONNECTION_ID </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">121</TD>
+<TD class="confluenceTd">SESSION_ID </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">122</TD>
+<TD class="confluenceTd">CONSUMER_ID </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">123</TD>
+<TD class="confluenceTd">PRODUCER_ID </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd">124</TD>
+<TD class="confluenceTd">BROKER_ID </TD>
+<TD class="confluenceTd"> </TD>
+</TR>
+</TBODY></TABLE>
<H4><A name="OpenWire-CommandFieldEncoding"></A>Command Field Encoding</H4>
@@ -366,7 +680,8 @@
<UL>
<LI>Java primitive types</LI>
<LI>String</LI>
- <LI>byte arrays</LI>
+ <LI>Byte Arrays</LI>
+ <LI>N Sized Byte Arrays</LI>
<LI>Throwable</LI>
<LI>Nested OpenWire commands</LI>
<LI>Nested OpenWire command arrays</LI>
@@ -390,7 +705,7 @@
+----------+ [ +-------+----------------+ ]
| not-<SPAN class="code-keyword">null</SPAN> | [ | size | encoded-string | ]
+----------+ [ +-------+----------------+ ]
-| <SPAN class="code-object">byte</SPAN> | [ | <SPAN
class="code-object">short</SPAN> | size bytes | ]
+| <SPAN class="code-object">byte</SPAN> | [ | <SPAN
class="code-object">short</SPAN> | size octects | ]
+----------+ [ +-------+----------------+ ]
[============================]</PRE>
</DIV></DIV>
@@ -414,6 +729,64 @@
</TR>
</TBODY></TABLE>
+<H6><A name="OpenWire-ByteArrayTypeEncoding"></A>Byte Array Type Encoding</H6>
+
+<P>Byte array fields may be null. If it is null then it encodes to a single
"0" byte.</P>
+
+<DIV class="code"><DIV class="codeContent">
+<PRE class="code-java"><SPAN class="code-object">byte</SPAN>-array encoding:
+ [=If not-<SPAN class="code-keyword">null</SPAN> is 1========]
++----------+ [ +------+--------------+ ]
+| not-<SPAN class="code-keyword">null</SPAN> | [ | size | data | ]
++----------+ [ +------+--------------+ ]
+| <SPAN class="code-object">byte</SPAN> | [ | <SPAN
class="code-object">int</SPAN> | size octects | ]
++----------+ [ +------+--------------+ ]
+ [=========================]</PRE>
+</DIV></DIV>
+
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> Field </TH>
+<TH class="confluenceTh"> Description </TH>
+</TR>
+<TR>
+<TD class="confluenceTd"> not-null </TD>
+<TD class="confluenceTd"> 1 if the byte array is not null, 0 if it is null
</TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> size </TD>
+<TD class="confluenceTd"> The number of bytes in the byte array </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> data </TD>
+<TD class="confluenceTd"> The data of the byte array </TD>
+</TR>
+</TBODY></TABLE>
+
+
+<H6><A name="OpenWire-NSizedByteArrayTypeEncoding"></A>N Sized Byte Array Type
Encoding</H6>
+
+<P>Fixed Size Byte array fields may NOT be null and their length must be N
length. Used for byte arrays that are always a fixed size.</P>
+<DIV class="code"><DIV class="codeContent">
+<PRE class="code-java">N-sized-<SPAN class="code-object">byte</SPAN>-array
encoding:
++-----------+
+| data |
++-----------+
+| N octects |
++-----------+</PRE>
+</DIV></DIV>
+
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> Field </TH>
+<TH class="confluenceTh"> Description </TH>
+</TR>
+<TR>
+<TD class="confluenceTd"> data </TD>
+<TD class="confluenceTd"> The data of the byte array </TD>
+</TR>
+</TBODY></TABLE>
+
<H6><A name="OpenWire-ThrowableTypeEncoding"></A>Throwable Type Encoding</H6>
<P>Throwable fields may be null. If it is null then it encodes to a single
"0" byte.</P>
@@ -473,7 +846,7 @@
</TR>
</TBODY></TABLE>
-<P>If the StackTraceEnabled encoding option is enabled after the exchange of
WireFormatInfo packets, then every Throwable filed will have stack trace data
appended to it.</P>
+<P>If the StackTraceEnabled encoding option is enabled after the exchange of
WIREFORMAT_INFO packets, then every Throwable filed will have stack trace data
appended to it.</P>
<H6><A name="OpenWire-NestedCommandTypeEncoding"></A>Nested Command Type
Encoding</H6>
@@ -562,7 +935,7 @@
<DIV id="site-footer">
Added by <A
href="http://goopen.org/confluence/users/viewuserprofile.action?username=jstrachan";>James
Strachan</A>,
last edited by <A
href="http://goopen.org/confluence/users/viewuserprofile.action?username=chirino";>Hiram
Chirino</A> on Dec 29, 2006
- (<A
href="http://goopen.org/confluence/pages/diffpages.action?pageId=101&originalId=15219";>view
change</A>)
+ (<A
href="http://goopen.org/confluence/pages/diffpages.action?pageId=101&originalId=15221";>view
change</A>)
(<A
href="http://goopen.org/confluence/pages/editpage.action?pageId=101";>edit
page</A>)
</DIV>
