You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by ch...@apache.org on 2006/12/28 20:55:28 UTC
svn commit: r490779 - in /incubator/activemq/site: openwire.html
protocols.html
Author: chirino
Date: Thu Dec 28 11:55:27 2006
New Revision: 490779
URL: http://svn.apache.org/viewvc?view=rev&rev=490779
Log:
Latest export from confluence
Modified:
incubator/activemq/site/openwire.html
incubator/activemq/site/protocols.html
Modified: incubator/activemq/site/openwire.html
URL: http://svn.apache.org/viewvc/incubator/activemq/site/openwire.html?view=diff&rev=490779&r1=490778&r2=490779
==============================================================================
--- incubator/activemq/site/openwire.html (original)
+++ incubator/activemq/site/openwire.html Thu Dec 28 11:55:27 2006
@@ -177,8 +177,8 @@
<UL class="alternate" type="square">
<LI><A href="web-console.html" title="Web Console">Web Console</A></LI>
- <LI><A href="jca-container.html" title="JCA Container">JCA Container</A></LI>
<LI><A href="hermes-jms.html" title="Hermes Jms">Hermes Jms</A></LI>
+ <LI><A href="activemq-performance-module-users-manual.html" title="ActiveMQ Performance Module Users Manual">Maven2 Performance Plugin</A></LI>
<LI><SPAN class="nobr"><A href="http://jakarta.apache.org/jmeter" title="Visit page outside Confluence" rel="nofollow">JMeter<SUP><IMG class="rendericon" src="http://goopen.org/confluence/images/icons/linkext7.gif" height="0" width="0" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
</UL>
@@ -222,7 +222,6 @@
<H3><A name="Navigation-Tests"></A>Tests</H3>
<UL class="alternate" type="square">
- <LI><A href="activemq-performance-module-users-manual.html" title="ActiveMQ Performance Module Users Manual">Maven2 Performance Plugin</A></LI>
<LI><A href="integration-tests.html" title="Integration Tests">Integration Tests</A></LI>
<LI><A href="benchmark-tests.html" title="Benchmark Tests">Benchmark Tests</A></LI>
<LI><A href="jmeter-performance-tests.html" title="JMeter Performance Tests">JMeter Performance Tests</A></LI>
@@ -283,41 +282,180 @@
</UL>
-<H3><A name="OpenWire-Destinationmarshalling"></A>Destination marshalling</H3>
+<H3><A name="OpenWire-Specification"></A>Specification</H3>
+
+<H4><A name="OpenWire-Overview"></A>Overview</H4>
+
+<P>OpenWire is used to marshal objects to byte arrays and back. We will refer to the marshaled objects as commands. All data types are encoded in big-endian/network byte order. </P>
+
+<P>A TCP network connection would see multiple commands back to back on the stream. Commands are not delimited in anyway and are variable sized.</P>
+
+<DIV class="code"><DIV class="codeContent">
+<PRE class="code-java">+---------+ +---------+ +---------+
+| command | | command | .... | command |
++---------+ +---------+ +---------+</PRE>
+</DIV></DIV>
+
+<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>
+
+<DIV class="code"><DIV class="codeContent">
+<PRE class="code-java">+------------------------+ +---------+ +---------+ +---------+
+| WireFormatInfo command | | command | | command | .... | command |
++------------------------+ +---------+ +---------+ +---------+</PRE>
+</DIV></DIV>
+
+<H4><A name="OpenWire-CommandEncoding"></A>Command Encoding</H4>
+
+<P>Every command is encoded as follows:</P>
+
+<DIV class="code"><DIV class="codeContent">
+<PRE class="code-java">0 4 5 size+4
++--------+--------+--------------------------+
+| size | type | command-specific-content |
++--------+--------+--------------------------+
+ 4 bytes | 1 <SPAN class="code-object">byte</SPAN> | (size-1) bytes</PRE>
+</DIV></DIV>
+
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> Field </TH>
+<TH class="confluenceTh"> Description </TH>
+</TR>
+<TR>
+<TD class="confluenceTd"> size </TD>
+<TD class="confluenceTd"> Holds how many subsequent bytes are in the the command </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> type </TD>
+<TD class="confluenceTd"> Command type identifier </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> command-specific-content </TD>
+<TD class="confluenceTd"> The data for the command. It is encoding depends on the type used </TD>
+</TR>
+</TBODY></TABLE>
+
+<P>If a command type does not have any command specific content, then size would be 1.</P>
+
+<H5><A name="OpenWire-TheSizePrefixDisabledEncodingOption"></A>The SizePrefixDisabled Encoding Option</H5>
+
+<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 be encoded as follows:</P>
+
+<DIV class="code"><DIV class="codeContent">
+<PRE class="code-java">0 1 n
++-------+--------------------------+
+| type | command-specific-content |
++-------+--------------------------+
+ 1 <SPAN class="code-object">byte</SPAN> | size depends on content</PRE>
+</DIV></DIV>
+
+
+<H4><A name="OpenWire-CommandFieldEncoding"></A>Command Field Encoding</H4>
+
+<P>All OpenWire commands use the same algorithm when encoding their fields. The algorithm restricts commands to use fields that are of the following type:</P>
+
+<UL>
+ <LI>Java primitive types</LI>
+ <LI>String</LI>
+ <LI>Throwable</LI>
+ <LI>OpenWire commands</LI>
+</UL>
+
+
+<P>Notice that OpenWire commands can use other OpenWire commands in it's fields. Care must be taken that only acyclic graphs of commands are marshaled.</P>
+
+<H5><A name="OpenWire-LooseEncoding"></A>Loose Encoding</H5>
-<P>We write a byte first to describe the type of destination.</P>
+<P>The fields of a command use "loose encoding" by default which encode an object field to a marshaled field of the equivalent size. Loose encoding is simple to implement does not add much CPU overhead to the marshaling/unmarshaling process.</P>
+
+<H6><A name="OpenWire-PrimitiveTypeEncoding"></A>Primitive Type Encoding</H6>
+
+<P>Table of primitive types and their encoded length:</P>
<TABLE class="confluenceTable"><TBODY>
<TR>
-<TH class="confluenceTh"> Byte value </TH>
-<TH class="confluenceTh"> Type of Destination </TH>
-<TH class="confluenceTh"> See </TH>
+<TH class="confluenceTh"> Primitive Type </TH>
+<TH class="confluenceTh"> Marshalled length </TH>
</TR>
<TR>
+<TD class="confluenceTd"> byte </TD>
<TD class="confluenceTd"> 1 </TD>
-<TD class="confluenceTd"> JMS Topic </TD>
-<TD class="confluenceTd"> ActiveMQDestination.ACTIVEMQ_TOPIC </TD>
</TR>
<TR>
+<TD class="confluenceTd"> char </TD>
+<TD class="confluenceTd"> 2 </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> short </TD>
<TD class="confluenceTd"> 2 </TD>
-<TD class="confluenceTd"> JMS Temporary Topic </TD>
-<TD class="confluenceTd"> ActiveMQDestination.ACTIVEMQ_TEMPORARY_TOPIC </TD>
</TR>
<TR>
-<TD class="confluenceTd"> 3 </TD>
-<TD class="confluenceTd"> JMS Queue </TD>
-<TD class="confluenceTd"> ActiveMQDestination.ACTIVEMQ_QUEUE </TD>
+<TD class="confluenceTd"> int </TD>
+<TD class="confluenceTd"> 4 </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> long </TD>
+<TD class="confluenceTd"> 8 </TD>
</TR>
<TR>
+<TD class="confluenceTd"> float </TD>
<TD class="confluenceTd"> 4 </TD>
-<TD class="confluenceTd"> JMS Temporary Queue </TD>
-<TD class="confluenceTd"> ActiveMQDestination.ACTIVEMQ_TEMPORARY_QUEUE </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> double </TD>
+<TD class="confluenceTd"> 8 </TD>
+</TR>
+</TBODY></TABLE>
+
+<H6><A name="OpenWire-StringTypeEncoding"></A>String Type Encoding</H6>
+
+<P>Strings fields may be null. If it is null then it encodes to a single "0" byte.<BR>
+If it is not null, then it encodes to:</P>
+
+<DIV class="code"><DIV class="codeContent">
+<PRE class="code-java">0 1 3 n
++-------+---------+----------------+
+| 1 | size | encoded-string |
++-------+---------+----------------+
+ 1 <SPAN class="code-object">byte</SPAN> | 2 bytes | size bytes</PRE>
+</DIV></DIV>
+
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> Field </TH>
+<TH class="confluenceTh"> Description </TH>
+</TR>
+<TR>
+<TD class="confluenceTd"> size </TD>
+<TD class="confluenceTd"> The number of bytes of the UTF-8 Encoded string </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> encoded-string </TD>
+<TD class="confluenceTd"> The UTF-8 encoded form of the string </TD>
</TR>
</TBODY></TABLE>
-<P>Then we write the destination string (which may have operations set on it using a URL style syntax).</P>
-<H3><A name="OpenWire-Implementationdetails"></A>Implementation details</H3>
+<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>
+
+
+<DIV class="code"><DIV class="codeContent">
+<PRE class="code-java">[ If is-<SPAN class="code-keyword">null</SPAN> == 1 -----------------------------------------------------------------------------]
+ [ [ If StackTraceEnabled encoding option is enabled.-----------] ]
+ [ [ [-- Repeated size times ---------------------] ] ]
++---------+ [ +----------------+---------+ [ +---------+ [ +--------+--------+--------+-------------+ ] ] ]
+| is-<SPAN class="code-keyword">null</SPAN> | [ | exception-name | message | [ | size | [ | class | method | file | line number | ] ] ]
++---------+ [ +----------------+---------+ [ +---------+ [ +--------+--------+--------+-------------+ ] ] ]
+| 1 <SPAN class="code-object">byte</SPAN> | [ | string | string | [ | 2 bytes | [ | string | string | string | 4 bytes | ] ] ]</PRE>
+</DIV></DIV>
+
+<H5><A name="OpenWire-TightEncoding"></A>Tight Encoding</H5>
+
+
-<P>We use a javadoc tag @Transient to mark any properties on the Java command objects as being transient caches and so not marshalled over the OpenWire transport.</P></DIV>
+<P>By default </P></DIV>
</DIV>
</TD>
@@ -327,8 +465,8 @@
</DIV>
<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=jstrachan">James Strachan</A> on Oct 28, 2006
- (<A href="http://goopen.org/confluence/pages/diffpages.action?pageId=101&originalId=14458">view change</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=15216">view change</A>)
(<A href="http://goopen.org/confluence/pages/editpage.action?pageId=101">edit page</A>)
</DIV>
Modified: incubator/activemq/site/protocols.html
URL: http://svn.apache.org/viewvc/incubator/activemq/site/protocols.html?view=diff&rev=490779&r1=490778&r2=490779
==============================================================================
--- incubator/activemq/site/protocols.html (original)
+++ incubator/activemq/site/protocols.html Thu Dec 28 11:55:27 2006
@@ -177,8 +177,8 @@
<UL class="alternate" type="square">
<LI><A href="web-console.html" title="Web Console">Web Console</A></LI>
- <LI><A href="jca-container.html" title="JCA Container">JCA Container</A></LI>
<LI><A href="hermes-jms.html" title="Hermes Jms">Hermes Jms</A></LI>
+ <LI><A href="activemq-performance-module-users-manual.html" title="ActiveMQ Performance Module Users Manual">Maven2 Performance Plugin</A></LI>
<LI><SPAN class="nobr"><A href="http://jakarta.apache.org/jmeter" title="Visit page outside Confluence" rel="nofollow">JMeter<SUP><IMG class="rendericon" src="http://goopen.org/confluence/images/icons/linkext7.gif" height="0" width="0" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
</UL>
@@ -222,7 +222,6 @@
<H3><A name="Navigation-Tests"></A>Tests</H3>
<UL class="alternate" type="square">
- <LI><A href="activemq-performance-module-users-manual.html" title="ActiveMQ Performance Module Users Manual">Maven2 Performance Plugin</A></LI>
<LI><A href="integration-tests.html" title="Integration Tests">Integration Tests</A></LI>
<LI><A href="benchmark-tests.html" title="Benchmark Tests">Benchmark Tests</A></LI>
<LI><A href="jmeter-performance-tests.html" title="JMeter Performance Tests">JMeter Performance Tests</A></LI>