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.

OpenWire is used to marshal objects to byte arrays and back. We will refer to the marshaled objects as commands.

A TCP network connection would see multiple commands back to back on the stream. Commands are not delimited in anyway and are variable sized.

All data primitive types used in the encoded commands are encoded in big-endian/network byte order.

primitive types and encoding:
+             |               |               |               |               |               |               
++----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ 
+| byte     | | | char      | | | short     | | | int       | | | long      | | | float     | | | double    | 
++----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ 
+| 1 octect | | | 2 octects | | | 2 octects | | | 4 octects | | | 8 octects | | | 4 octects | | | 8 octects | 
++----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ 
+             |               |               |               |               |               |

Wire Format Negotiation

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.

[=If SizePrefixDisabled =] 
+command encoding:
+[=If SizePrefixDisabled =] 
 [ option is not enabled. ]
-[ +---------+            ] +--------+--------------------------+
-[ | size    |            ] | type   | command-specific-content |
-[ +---------+            ] +--------+--------------------------+
-[ | 4 bytes |            ] | 1 byte | (size-1) bytes           |
-[ +---------+            ] +--------+--------------------------+
+[ +------+               ] +------+-------------------------+
+[ | size |               ] | type | command-specific-fields |
+[ +------+               ] +------+-------------------------+
+[ | int  |               ] | byte | (size-1) bytes          |
+[ +------+               ] +------+-------------------------+
 [========================]

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.

Notice that OpenWire commands can nest other OpenWire commands in it's fields. Care must be taken that only acyclic graphs of commands are marshaled.

Loose Encoding

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.

Primitive Type Encoding

Primitive Type	Marshalled length
byte	1
char	2
short	2
int	4
long	8
float	4
double	8

String Type Encoding

Strings fields may be null. If it is null then it encodes to a single "0" byte.
-If it is not null, then it encodes to:

String Encoding:
-             [=If not-null is 1=============]
-+----------+ [ +---------+----------------+ ]
-| not-null | [ | size    | encoded-string | ]
-+----------+ [ +---------+----------------+ ]
-| 1 byte   | [ | 2 bytes | size bytes     | ]
-+----------+ [ +---------+----------------+ ]
-             [==============================]

string encoding:
+             [=If not-null is 1===========]
++----------+ [ +-------+----------------+ ]
+| not-null | [ | size  | encoded-string | ]
++----------+ [ +-------+----------------+ ]
+| byte     | [ | short | size bytes     | ]
++----------+ [ +-------+----------------+ ]
+             [============================]

Throwable Encoding:
-             [=If not-null is 1=============================================================================]
-             [                               [=If StackTraceEnabled option is enabled.====================] ]
-             [                               [             [=Repeated size times========================] ] ]
-+----------+ [ +----------------+---------+  [ +---------+ [ +--------+--------+--------+-------------+ ] ] ]
-| not-null | [ | exception-name | message |  [ | size    | [ | class  | method | file   | line-number | ] ] ]
-+----------+ [ +----------------+---------+  [ +---------+ [ +--------+--------+--------+-------------+ ] ] ]
-| 1 byte   | [ | string         | string  |  [ | 2 bytes | [ | string | string | string | 4 bytes     | ] ] ]
-+----------+ [ +----------------+---------+  [ +---------+ [ +--------+--------+--------+-------------+ ] ] ]
-             [                               [             [============================================] ] ]
-             [                               [============================================================] ]
-             [==============================================================================================]

throwable encoding:
+             [=If not-null is 1===========================================================================]
+             [                               [=If StackTraceEnabled option is enabled.==================] ]
+             [                               [             [=Repeated size times======================] ] ]
++----------+ [ +----------------+---------+  [ +-------+ [ +--------+--------+--------+-------------+ ] ] ]
+| not-null | [ | exception-name | message |  [ | size  | [ | class  | method | file   | line-number | ] ] ]
++----------+ [ +----------------+---------+  [ +-------+ [ +--------+--------+--------+-------------+ ] ] ]
+| byte     | [ | string         | string  |  [ | short | [ | string | string | string | int         | ] ] ]
++----------+ [ +----------------+---------+  [ +-------+ [ +--------+--------+--------+-------------+ ] ] ]
+             [                               [           [============================================] ] ]
+             [                               [==========================================================] ]
+             [============================================================================================]

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.

Nested Command Type Encoding

Tight Encoding

Nested command fields may be null. If it is null then it encodes to a single "0" byte.

nested-object encoding:
+             [=If not-null is 1===================]
++----------+ [ +------+-------------------------+ ]
+| not-null | [ | type | command-specific-fields | ]
++----------+ [ +------+-------------------------+ ]
+| byte     | [ | byte | variable sized          | ]
++----------+ [ +------+-------------------------+ ]
+             [====================================]

Field	Description
not-null	1 if the Throwable not null, 0 if the Throwable is null
type	Command type identifier
command-specific-fields	The data for the command. It is encoding depends on the type used

Cached Nested Command Type Encoding

Nested Command types can be cached so that subsequent marshaling operations of the same object result in a smaller on the wire size. By default the CacheEnabled option is not enabled and therefore standard nested-object encoding is used.

cached-object-encoding:
+[=If CacheEnabled option is enabled=====================]
+[                       [=If new-value is 1===========] ]
+[ +-----------+-------+ [ +-------------------------+ ] ]
+[ | new-value | key   | [ | command-specific-fields | ] ]
+[ +-----------+-------+ [ +-------------------------+ ] ]
+[ | byte      | short | [ | nested-object           | ] ]
+[ +-----------+-------+ [ +-------------------------+ ] ]
+[                       [=============================] ]
+[=====================================================] ]
+
+[=If CacheEnabled option is disabled =]
+[ +-------------------------+         ]
+[ | command-specific-fields |         ]
+[ +-------------------------+         ]
+[ | nested-object           |         ]
+[ +-------------------------+         ]
+[=====================================]

Field	Description
new-value	1 if the value is not in the cache, 0 if it already is in the cache
key	Key used to identify the value in the cache
command-specific-fields	The data for the command. It is encoding depends on the type used