The CDR Resource Adaptor is configured using resource adaptor configuration properties and a configuration profile table.

The configuration is processed when you activate the resource adaptor or reconfigure it while it’s active.

Resource adaptor configuration properties

The CDR Resource Adaptor is configured using following configuration properties:

Property What it does Default 
 CdrStreamConfigurationProfileTable

The name of a profile table defining CDR streams configuration. Each profile represents a CDR stream. The table must use the CDR Stream Configuration profile specification.

 
 CdrStreamConfiguration
 
 DefaultStream

The stream name to be used when an SBB requests a CDR write using a resource adaptor provider interface method without a stream name parameter. If the stream name is provided, it must match the name of a profile defined in CdrStreamConfigurationProfileTable.

Warning If the value is not set, an SBB CDR write request with no stream name provided will result in an exception being thrown and a SLEE alarm raised.

empty

 
 ArchiveQueueSizeAlarmRaise

If the archive queue size exceeds this value, the cdr.archive-queue-size alarm is raised.

The value must be >= 10.

 
 120
 
 ArchiveQueueSizeAlarmClear

If the archive queue size decreases below this value mthe cdr.archive-queue-size active alarm is cleared.

The value must be >= 5.

 
 80

Profile configuration

The CDR Resource Adaptor manages a set of CDR streams. A CDR stream is configured by creating a profile in CdrStreamConfigurationProfileTable. The profile name is used as the CDR stream name.

Attribute What it does Default 
 OutputDirectoryName

Name of the directory into which the CDRs will be written. The resource adaptor must have write permissions for it.

This parameter is mandatory.

The directory will be created if it does not exist when the resource adaptor configuration is verified. This will happen before the resource adaptor is activated. The directory will also be created if it is missing when a new CDR file is created.

Note

The resource adaptor requires a Java file permission to write to the directory specified here.

This property supports property expansion.
Warning

In a clustered environment, each node manages its own set of CDR files. Several nodes may safely write to the same output directory; but care should be taken to ensure that the final output filenames do not collide. Including a %n format specifier (node ID) as part of the FilenamePattern is the safest way to ensure this.

 
 ${rhino.dir.home}${/}cdr
 
 CdrFileType

The CDR file type to use. Either Text or Binary.

 
 Binary
 
 FilenamePattern

Pattern used to generate final CDR filenames.

Note This property supports property expansion and filename patterns. 
 cdr_%n_%M_%t.log
 
 TempFilePrefix

Prefix used as part of the temporary CDR filename. That is, the file to which currently generated call data records are written.

The full filename format for temporary CDR file is:

TempFilePrefix RHINO NODE ID CDR STREAM NAME _*.tmp

where * denotes a random number and CDR STREAM NAME represents the name of the CDR stream with characters other than a-z, A-Z, 0-9,.,_,- replaced by _.

Note This property supports property expansion. 
 cdr_
 
 MaxSize

Approximate maximum size in bytes before a new CDR file is started. After a CDR is written, the total file size is compared to MaxSize.

  • If the current file size is larger, it is completed.

  • If MaxSize is 0, no size-based rollover is done.

 
1,000,000

bytes (approx 1MB)

 
 MaxCdrs

Number of CDRs to be written to a CDR file before a new file is started.

  • If MaxCdrs is 0, no size-based rollover is done.

 
0

(no rollover)

 
 MaxInterval

Number of milliseconds of operation before time-based file rollover. If a CDR file is used for more than MaxInterval seconds without being rolled over due to line- or size-based limits, it is completed anyway.

The value must be either 0 or >= 1000.

Note If CreateEmptyFiles is True, at least one CDR file is created every MaxInterval seconds, even if no CDRs are written. 
0

(no rollover)

 
 Header

If True, a one-line header containing the start time of the text CDR file is put at the start of each file.

Note This attribute is ignored if CdrFileType is set to Binary. For binary CDR files, a record containing the header is always present. 
 True
 
 Footer

If True, a one-line footer containing the end time of the text CDR file is put at the end of each file.

Note This attribute is ignored if CdrFileType is set to Binary. For binary CDR files, a record containing the footer is always present. 
 True
 
 CreateEmptyFiles

If True, a new CDR file is created immediately on resource adaptor activation, and whenever a CDR file is rolled over.

If False, a new file is created when writing the first CDR record after activation or rollover of a CDR file.

 
 False
 
 ArchiveCommand

Command to run on each CDR file completion.

{0} in the command line denotes the absolute path to the CDR file.

If empty, no command is run.

Note

The resource adaptor must have execute permissions for the specified command. The default permissions allow it to run commands in a directory named cdr-bin in the Rhino home directory and the Rhino node directory.

This property supports property expansion.

empty

 
 Charset

Character encoding to use for the output file.

 
 ISO-8859-1
 
 WriteTimeout

Time, in milliseconds, to wait for a CDR write to complete before returning a timeout error to the calling SBB.

The value must either 0 or >= 200.

If 0, the resource adaptor adds the CDR to a queue and returns immediately. This can be used to reduce latency in writing CDRs, but means that queued CDRs are lost in the event of a write error or node failure.

Note
See also
CDR Stream persistence, error handling, and operational state.
Warning If this property is set to 0, then WriteSync should generally also be set to False, because the resource adaptor will already have returned to the calling SBB before FileDescriptor.sync() is called. 
5000

(5 seconds)

 
 WriteRetry

Delay, in milliseconds, to wait after a CDR write error before attempting another CDR write. Value must be greater than or equal to 500.

Note
See also
CDR Stream persistence, error handling, and operational state. 
30000

(30 seconds)

 
 WriteSync

If True, FileDescriptor.sync() is called after writing CDRs, to flush them to disk before reporting success to the calling SBB.

If False, the call to sync() is skipped, resulting in considerably less disk I/O but a weaker guarantee to the calling SBB.

Note
See also
CDR Stream persistence, error handling, and operational state.
Warning If WriteTimeout is 0, then this value has no effect on when control is returned to the calling SBB. 
 True

File permissions

The security permission spec in the resource adaptor descriptor contains the following default permissions:

// rhino.dir.home - the install directory for Rhino SDK, the node-nnn directory for Rhino Production.
permission java.io.FilePermission "${rhino.dir.home}${/}cdr", "read, write, execute";
permission java.io.FilePermission "${rhino.dir.home}${/}cdr${/}-", "read, write, execute";
permission java.io.FilePermission "${rhino.dir.home}${/}cdr-bin", "read, execute";
permission java.io.FilePermission "${rhino.dir.home}${/}cdr-bin${/}-", "read, execute";
// rhino.dir.base - the install directory for both Rhino Production and Rhino SDK
permission java.io.FilePermission "${rhino.dir.base}${/}cdr", "read, write, execute";
permission java.io.FilePermission "${rhino.dir.base}${/}cdr${/}-", "read, write, execute";
permission java.io.FilePermission "${rhino.dir.base}${/}cdr-bin", "read, execute";
permission java.io.FilePermission "${rhino.dir.base}${/}cdr-bin${/}-", "read, execute";
// deprecated, retained for compatibility
permission java.io.FilePermission "${rhino.dir.home}${/}archive-cdr-log.sh", "read, execute";
permission java.io.FilePermission "${rhino.dir.home}${/}cdr${/}archive-cdr-log.sh", "execute";
permission java.io.FilePermission "${rhino.dir.base}${/}archive-cdr-log.sh", "read, execute";
permission java.io.FilePermission "${rhino.dir.base}${/}cdr${/}archive-cdr-log.sh", "read, execute";

Specifying an output directory or archive command that is not covered by the above permissions will require a new permission to be added to the deployable unit, using a Rhino management tool.

The Rhino Element Manager is the simplest way to make manual changes, and there is an Ant task for scripted deployment.

Filename patterns

The FilenamePattern configuration parameter should include format specifiers that are replaced to generate unique filenames. The supported specifiers are:

Specifier Description 
 %%

A literal % character

 
 %t

File completion timestamp, as milliseconds since Jan 1 1970 00:00 UTC

 
 %T

File creation timestamp, as milliseconds since Jan 1 1970 00:00 UTC

 
 %s

Auto-incrementing file completion sequence number, starting at 1

Warning Deactivation and activation of a CDR resource adaptor entity will result in resetting the sequence number to 1. To obtain a unique filename, use this pattern together with one of timestamp patterns. 
 %d

File completion timestamp, formatted as yyyyMMddHHmmss

 
 %D

File creation timestamp, formatted as yyyyMMddHHmmss

 
 %n

Rhino node ID responsible for creating this file

 
 %M

CDR stream name where characters other than a-z, A-Z, 0-9,.,_,- are replaced by _

Property expansion

Certain CDR resource adaptor configuration properties support system property expansion. This mechanism is similar to expanding variables in a shell. That is, when a string like ${some.property} appears as part of a configuration property value, it will be expanded to the value of the system property. For example,

${user.home}/cdr

will expand ${user.home} to use the value of the user.home system property. If that property’s value is /home/rhino, then the above is equivalent to

/home/rhino/cdr

Two useful properties for specifying paths (used in the default file permissions) are rhino.dir.home and rhino.dir.base:

Property What it refers to 
 rhino.dir.home

the install directory for Rhino SDK, the node-nnn directory for Rhino Production

 
 rhino.dir.base

the install directory for both Rhino Production and Rhino SDK

In order to assist in platform-independent configuration, you can also use the special notation of ${/}, which is a shortcut for ${file.separator}.

CDR stream persistence, error handling, and operational state

If stream configuration attributes WriteTimeout is set to a non-zero value and WriteSync is set to True, the CDR resource adaptor ensures that all written CDR data has been flushed to disk (using java.io.FileDescriptor.sync()) before returning to an SBB. In that case, after a successful writeCDR call, SBBs should assume that all CDR data has been saved to disk.

Warning The exact behaviour of java.io.FileDescriptor.sync() is dependent on the operating system, drivers and hardware. In some environments the sync() call may return successfully before the data is permanently stored.

If there is a write error while writing the CDR, and the WriteTimeout stream configuration attribute is set to a non-zero value, this will be reported to the SBB as an IOException. If the CDR could not be written within the configured WriteTimeout, then a com.opencloud.slee.resources.cdr.WriteTimeoutException (a subclass of IOException) is reported to the SBB.

Note In general, receiving an exception means that the CDR resource adaptor could not guarantee that the CDR was successfully written.

Under normal operation, a CDRProvider.isOperational() call directed towards any stream returns True. If a write error or timeout error occurred recently for a stream, a isOperational() call towards that stream returns False. All attempts to write CDRs to such streams are immediately rejected without attempting to write them to disk. This state persists for 2 * WriteTimeout milliseconds (for timeout errors) or WriteRetry milliseconds (for write errors).

Additionally, isOperational() returns False if the resource adaptor entity is currently inactive (but was successfully activated at least once). Services should test isOperational() if they wish to behave differently when CDR writing is unavailable.

In the event of a write error, or if a Rhino node unexpectedly exits, partial CDR files may be left in the CDR directory. With the default configuration value of TempFilePrefix, these files are named cdr_nodeID_streamName_*.tmp where * denotes a random number. If they contain useful CDR data, these files will need to be manually examined and processed.

Active reconfiguration

The resource adaptor supports active reconfiguration. You can update configuration properties without having to deactivate the resource adaptor entity.

Warning
Changes to stream configuration profiles are not automatically discovered by the resource adaptor

For the stream configuration to take effect, you must trigger a configuration reload after changing the profile table. To trigger a configuration reload…​

  • using the Rhino command-line console: run updateraentityconfigproperties <entity-name>

  • using the Rhino Element Manager: edit and save the resource adaptor entity configuration without changing any configuration property values.

When the configuration is updated, the resource adaptor will compare the new configuration with the previous valid configuration to determine which streams need to be:

  • stopped and removed — when a profile representing the stream was removed; that is, there is no profile with a profile name equal to the CDR stream name

  • created and started — when a new profile was added

  • reconfigured — when attributes of an existing profile were changed; that is, attribute values of a profile with the same CDR stream name are different than attribute values previously used by the resource adaptor.

If errors are encountered when adding new streams or reconfiguring existing streams, the configuration update is aborted. No changes to the existing "in use" configuration are made.

Note Changing configuration of a stream that is in use results in a rollover of the stream’s CDR file. The newly created CDR file is configured based on the updated stream configuration. CDRs will not be lost during stream reconfiguration.
Previous page Next page