This section describes the CDR Resource Adaptor support for writing binary CDR files.
Using the Google Protocol Buffers definition
Download package
The CDR resource adaptor uses Google Protocol Buffers version 2.3.0 — which is no longer available from the official website. Please download the package from here: protobuf-2.3.0.tar.gz. |
The CDR resource adaptor:
-
uses the Google Protocol Buffers (proto2 version of the protocol buffers language) to support writing CDR files with binary-encoded CDR records
-
enables SBBs to store any protocol buffer protocol message.
See also
Google’s Protocol Buffer documentation includes
an extensive description of the .proto file syntax and a tutorial on using the protocol buffers.
|
To use Protocol Buffers functionality in an SBB, the developer must:
-
Define a protocol buffer message that will be generated and written by creating a
.proto
file. -
Use the protocol buffer compiler to generate code that supports the creation, writing, and reading of the protocol buffer message specified in
.proto
file. -
Use the Java protocol buffer API in the SBB to create messages and pass them to the CDR resource adaptor for writing.
-
Package the generated protocol buffer code so that it can be used by the SBB at runtime (for example, include it in an
sbb.jar
or create and reference a library jar).
There is no need to package the protocol buffer library code itself, as it is already distributed as a library jar with the CDR resource adaptor package. |
Binary CDR file format
The binary CDR file format is specified as the protocol buffer’s .proto
file.
It is distributed as part of the CDR resource adaptor package in /etc/CdrFileFormat.proto
. Here’s what it looks like:
syntax = "proto2"; package com.opencloud.slee.resources.cdr.protobuf; option java_outer_classname = "CdrFileFormat"; message CdrFile { repeated Record record = 1; message Record { optional Header header = 1; optional MDescriptor messageDescriptor = 2; optional FDescriptor fileDescriptor = 3; optional BinaryCDR binaryCdr = 4; optional StringCDR stringCdr = 5; optional Footer footer = 6; optional DateTime timestamp = 7; optional EDescriptor extensionDescriptor = 8; } message Header { optional string ra_name = 1; optional string ra_vendor = 2; optional string ra_version = 3; optional string ra_release = 4; optional string ra_build = 5; optional string ra_revision = 6; optional string description = 7; optional string rhino_node = 8; optional string ra_entity = 9; optional string hostname = 10; } // Contains a single encoded FileDescriptorProto. // The descriptor can subsequently be referred to by 'fid' message FDescriptor { required int32 fid = 1; // FDescriptor id required bytes encoded_descriptor = 2; repeated int32 dependency = 3 [packed=true]; // List of dependencies, referring to previously-encoded fids } // Associates a 'mid' with a particular named message in a previously-encoded FileDescriptor message MDescriptor { required int32 mid = 1; // MDescriptor id required int32 fid = 2; required string message_name = 3; } message BinaryCDR { required int32 mid = 1; required bytes cdr = 2; repeated int32 eid = 3; } message StringCDR { required string cdr = 1; } message Footer { } message DateTime { required int64 milliseconds_since_epoch = 1; required sint32 zoneoffset_minutes = 2; } message EDescriptor { required int32 eid = 1; // EDescriptor id required int32 fid = 2; required string name = 3; } }
A CDR file is a collection of records. The first record in CDR file contains the header message; the last record in CDR file might be the footer message.
SBB-generated CDRs represented by protocol buffer messages are stored in the record as BinaryCDR
messages.
If the SBB generates text CDRs, they are stored in the record as StringCDR
messages.
A record that contains either a BinaryCDR
or StringCDR
message may also contain a timestamp representing the date
and time when the CDR was processed by stream’s write thread.
The stream’s write thread processes CDRs in batches; only the first CDR record in the batch contains a timestamp.
A record that contains either a BinaryCDR
or StringCDR
without a timestamp value should be processed assuming the
timestamp value is equal to the last encountered timestamp.
Whenever an SBB requests a write of a binary CDR (protocol buffer message), the resource adaptor checks if this type of
binary CDR is written, for the first time, in the current CDR file.
If it is, then the resource adaptor first generates and writes one or more records containing an FDescriptor
message,
followed by a record containing an MDescriptor
message.
These messages contain protocol buffer metadata that describe the format of the binary CDR (SBB-generated protocol
buffer message).
The encoded_descriptor
field of the FDescriptor
message contains encoded bytes representing a
com.google.protobuf.Descriptors.FileDescriptor
for the binary CDR (SBB-generated protocol buffer message) and can be
used to recreate and programmatically interrogate the protocol buffer’s description (effectively the .proto
file) of
the stored binary CDR records.
See also
For more information on how to use Descriptors.FileDescriptor , see the protocol buffer documentation on
Self-describing Messages, and the
Protocol Buffers Java API.
|
Extensions
The Google Protocol Buffers library supports the notion of extension fields.
Any message may contain multiple extension fields.
This enables storing additional information in a protocol buffer message without modifying the original message
definition (the .proto
file).
See also
For more information on extensions, see the protocol buffer documentation
Extensions.
|
When a binary CDR (protocol buffer message) is stored using the extension-supporting resource adaptor API call, the
extension definitions are included in the CDR file.
When the extension definition is used for the first time in a CDR file, the write of the BinaryCDR
message is
preceded with records representing metadata about the extension.
Extension metadata is represented by records containing one or more FDescriptor
messages followed by a single record
with an EDescriptor
message.
-
The
FDescriptor
contains encoded bytes representing acom.google.protobuf.Descriptors.FileDescriptor
(effectively the.proto
file), with the definition of the extension. -
The
EDescriptor
provides a name of the extension field and reference to theFDescriptor
containing the field definition. The mapping between the binary CDR and extensions used is persisted within the CDR file.
Binary CDR file processing
The CDR resource adaptor package contains tools for processing binary CDR files, described in Binary CDR file processing.