This section describes the CDR Resource Adaptor support for writing binary CDR files.

Using the Google Protocol Buffers definition

Warning
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.

Note
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:

  1. Define a protocol buffer message that will be generated and written by creating a .proto file.

  2. Use the protocol buffer compiler to generate code that supports the creation, writing, and reading of the protocol buffer message specified in .proto file.

  3. Use the Java protocol buffer API in the SBB to create messages and pass them to the CDR resource adaptor for writing.

  4. 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).

Tip 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:

Binary CDR file format
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.

Note
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).

Note
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 a com.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 the FDescriptor 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.

Previous page Next page