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>
![http://goopen.org/confluence/images/icons/linkext7.gif"](http://goopen.org/confluence/images/icons/linkext7.gif"){kind=link}