DcclCodecGroups
discussion for the blueprint https://blueprints.launchpad.net/dccl/+spec/dccl-codec-groups
Primary rationale: We want to improve the default codecs but preserve full backwards compatibility with version 2.
Add two new message level extensions that are ONLY valid in the root DCCL message: codec_group and codec_version. codec_version is an integer N that is identical to codec_group = "dccl.defaultN" used to indicate the default codec version the users want (currently either 2 or 3 for (Goby)-DCCL v2 or DCCL v3). If both are specified, codec_group takes precedence. The codec_group specified in the root message is inherited by child messages.
For example (this is similar to what's in dccl/test/dccl_codec_group)
message TestMsgGroup
{
option (dccl.msg).id = 2;
option (dccl.msg).max_bytes = 32;
option (dccl.msg).codec_group = "test.grouptest";
option (dccl.msg).codec_version = 3;
optional double d = 1;
repeated double d_repeat = 3 [(dccl.field).max_repeat=5];
optional EmbeddedMsg1 msg = 2;
}
message EmbeddedMsg1
{
optional double val = 1 [(dccl.field).min=0,
(dccl.field).max=100,
(dccl.field).precision=3];
optional EmbeddedMsg2 msg = 2;
}
message EmbeddedMsg2
{
optional double val = 1 [(dccl.field).min=0,
(dccl.field).max=100,
(dccl.field).precision=2];
}
dccl::Codec::info gives us (the codec is listed now to the right of the field size)
--------------------------- Header ---------------------------
dccl.id head...................................8
---------------------------- Body ----------------------------
TestMsgGroup...............................15-93 {test.grouptest}
1. d..................................11 {test.grouptest}
3. d_repeat[5]......................3-58 {test.grouptest}
2. msg..............................1-24 {test.grouptest}
1. val................................11 {test.grouptest}
2. msg..............................1-12 {test.grouptest}
1. val................................11 {test.grouptest}
Resolution of which codec to use is in this order:
- If (dccl.field).codec is explicitly set use that.
- If this is an embedded message type and (dccl.msg).codec is explicitly set in that message definition, then use that.
- If (dccl.msg).codec_group is set in the root message, use that.
- If (dccl.msg).codec_version = N is set in the root message, use codec_group = "dccl.defaultN"
- Use the (dccl.field).codec default (which is "dccl.default2").
For example:
message EmbeddedMsg1
{
option (dccl.msg).codec="dccl.default3"; //overrides codec_group
optional double val = 1 [(dccl.field).min=0,
(dccl.field).max=100,
(dccl.field).precision=3];
optional EmbeddedMsg2 msg = 2;
}
message EmbeddedMsg2
{
optional double val = 1 [(dccl.field).min=0,
(dccl.field).max=100,
(dccl.field).precision=2];
}
message TestMsgGroup
{
option (dccl.msg).id = 2;
option (dccl.msg).max_bytes = 32;
option (dccl.msg).codec_group = "test.grouptest";
option (dccl.msg).codec_version = 3; // isn't used because codec_group is specified
optional double d = 1 [(dccl.field).min=-100,
(dccl.field).max=126,
(dccl.field).precision=1,
(dccl.field).codec="dccl.default3"]; // overrides codec_group
repeated double d_repeat = 3 [(dccl.field).max_repeat=5];
optional EmbeddedMsg1 msg = 2;
}
gives
--------------------------- Header ---------------------------
dccl.id head...................................8
---------------------------- Body ----------------------------
TestMsgGroup...............................16-94 {test.grouptest}
1. d..................................12 {dccl.default3}
3. d_repeat[5]......................3-58 {test.grouptest}
2. msg..............................1-24 {dccl.default3}
1. val................................11 {test.grouptest}
2. msg..............................1-12 {test.grouptest}
1. val................................11 {test.grouptest}