This section describes CDR resource adaptor support for writing binary CDR files.

Binary CDR file support using Google Protobuf definition

The CDR resource adaptor:

  • uses the Google Protocol Buffers 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 Protobuf 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 creation, writing, and reading 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).

Note 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
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;
    }

    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;
        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;
        required int32 fid = 2;
        required string message_name = 3;
    }

    message BinaryCDR {
        required int32 mid = 1;
        required bytes cdr = 2;
    }

    message StringCDR {
        required string cdr = 1;
    }

    message Footer {
    }

    message DateTime {
      required int64 milliseconds_since_epoch = 1;
      required sint32 zoneoffset_minutes = 2;
    }

}

A CDR file is a collection of records. If the Header configuration property is set to True, the first record in CDR file contains the header message. Similarly, based on the Footer configuration property, 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. Each record that contains either a BinaryCDR or StringCDR message also includes a timestamp representing date and time when the CDR was generated.

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

Binary CDR file interrogation tools

The CDR resource adaptor package contains two user tools that can be used to display the content of a binary CDR file in text format.

Tool Description

listcdrs.py

A Python script that displays the content of a binary CDR file in text format.

Usage:

listcdrs.py CDRFILE
Note This script requires the Python protocol buffers module, which is available as part of a complete protocol buffers installation. (Depending on your operating system type and vendor, it might also be available as part of your standard software distribution system.)

listcdrs.sh

A shell script that starts a Java program capable of querying and displaying a binary CDR file’s content in text format.

Usage:

listcdrs.sh [--field field --regex regex] [--formatted] CDRFILE [CDRFILE]...
Tip To list possible values for the --field parameter, display the binary CDR file content without the --field parameter. Any text followed by = is a field name.

The --regex parameter takes a regular expression; only CDRs with matching field values display. The supported regular expression format is described in the Pattern class documentation.

The --formatted option results in using a multiline display format.

This tool also supports CDR binary files in gzip format. Each file that ends with a .gz suffix is treated as compressed. That is, there is no need to decompress such CDR files before running the tool.
Note Short usage message is displayed by each tool when invoked without parameters.
Previous page Next page