![]() Warning |
| title |
OpenWire Version 2 is not the latest version. |
|
| This article references OpenWire V2 which is no longer the latest version. The formatting and encoding rules in this article are still valid for later OpenWire versions, but later versions define additional fields in the OpenWire commands. The default setting settings shown in this article may not reflect the current defaults, see this page for the latest default OpenWire settings. |
... A TCP network connection would see multiple commands back to back on the stream. Commands are not delimited in anyway and are variable sized.
![]() Code Block |
+---------+ +---------+ +---------+
| command | | command | .... | command |
+---------+ +---------+ +---------+
|
All data primitive types used in the encoded commands are encoded in big-endian/network byte order.
![]() Code Block |
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 |
+----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+ | +-----------+
| | | | | |
|
... 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.
![]() Code Block |
+-------------------------+ +---------+ +---------+ +---------+
| WIREFORMAT_INFO command | | command | | command | .... | command |
+-------------------------+ +---------+ +---------+ +---------+
|
... Every command is encoded as follows:
![]() Code Block |
command encoding:
[=If SizePrefixDisabled =]
[ option is not enabled. ]
[ +------+ ] +------+-------------------------+
[ | size | ] | type | command-specific-fields |
[ +------+ ] +------+-------------------------+
[ | int | ] | byte | (size-1) octects |
[ +------+ ] +------+-------------------------+
[========================]
|
... Strings fields may be null. If it is null then it encodes to a single "0" byte.
![]() Code Block |
string encoding:
[=If not-null is 1===========]
+----------+ [ +-------+----------------+ ]
| not-null | [ | size | encoded-string | ]
+----------+ [ +-------+----------------+ ]
| byte | [ | short | size octects | ]
+----------+ [ +-------+----------------+ ]
[============================]
|
... Byte array fields may be null. If it is null then it encodes to a single "0" byte.
![]() Code Block |
byte-array encoding:
[=If not-null is 1========]
+----------+ [ +------+--------------+ ]
| not-null | [ | size | data | ]
+----------+ [ +------+--------------+ ]
| byte | [ | int | size octects | ]
+----------+ [ +------+--------------+ ]
[=========================]
|
... 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.
![]() Code Block |
N-sized-byte-array encoding:
+-----------+
| data |
+-----------+
| N octects |
+-----------+
|
... Throwable fields may be null. If it is null then it encodes to a single "0" byte.
![]() Code Block |
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 | ] ] ]
+----------+ [ +----------------+---------+ [ +-------+ [ +--------+--------+--------+-------------+ ] ] ]
[ [ [============================================] ] ]
[ [==========================================================] ]
[============================================================================================]
|
... Nested command fields may be null. If it is null then it encodes to a single "0" byte.
![]() Code Block |
nested-object encoding:
[=If not-null is 1===================]
+----------+ [ +------+-------------------------+ ]
| not-null | [ | type | command-specific-fields | ]
+----------+ [ +------+-------------------------+ ]
| byte | [ | byte | variable sized | ]
+----------+ [ +------+-------------------------+ ]
[====================================]
|
... 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.
![]() Code Block |
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 | ]
[ +-------------------------+ ]
[=====================================]
|
... |
