CORAL Component documentation: CoralBase

Ioannis Papadopoulos

CERN

October 2005


1. Introduction

1.1. Purpose of the component

This component defines a few C++ types mapping to special SQL types (Blob, Date, TimeStamp) and the AttributeList class, which is the main data placeholder in the CORAL public API.

1.2. Known problems and restrictions

  • The Blobs can hold binary data that fit entirely in the memory available by the operating system.
  • The AttributeList may hold variables of primitive C++ types, std::string types and the coral::Blob, coral::Date and coral::TimeStamp types.

1.3. Repository of the component

:pserver:anonymoys@coral.cvs.cern.ch:/cvs/coral/coral/CoralBase

1.4. Glossary

  • BLOB The abbreviation for a Binary Large OBject

2. Description of the CoralBase API functionality

2.1. Data Types

All operations with the CORAL API use exclusivelly C++ types. No SQL types are exposed. This means that column variables appearing in table descriptions and query result sets are mapped to a compatible C++ types. The C++ types supported in CORAL are:

  • All the primitive C++ types: bool, (unsigned) char, (unsigned) short, (unsigned) int, (unsigned) long, float, (long) double.
  • The string type of the C++ standard library: std::string
  • The platform independent 64-bit integer types provided by SEAL (SealBase): seal::IntBits<64>::SLeast (signed 64-bit integer), seal::IntBits<64>::ULeast (unsigned 64-bit integer)
  • The BLOB type defined by CORAL (CoralBase): coral::Blob
  • The DATE type defined by CORAL (CoralBase): coral::Date
  • The TIMESTAMP type defined by CORAL (CoralBase): coral::TimeStamp

The Blob type is a wrapper class of a contiguous memory segment, which can be resized on user request. This type is suitable for I/O of raw data or LOB SQL types.

The Date and TimeStamp types wrap the seal::Time class in order to perform I/O to tables containing DATE and TIMESTAMP columns.

2.2. The AttributeList

The main interface which is used for all the data exchange between a CORAL-based software component and a relational database is the AttributeList class. It is a container of Attributes, which are named variables of simple types (listed above). An Attribute holds the actual data of the named variable and its Specification, which holds its name and its C++ type. The Attribute also holds the null-ness of the variable, a concept which is inherent in SQL variables but absent in C++ ones. The AttributeList can therefore be thought of as a buffer holding the data of a table row. It is used both for input and output operations.

The Attribute class provides access to the actual data which is either fast or accompanied with type checking. This allows a user to choose the access method that is mostly relevant to the use case or problem in consideration.

The AttributeList and Attribute classes have been designed and optimized for database I/O operations. For this reason the following capabilities have been added to their basic functionality:

Sharing of data
The actual C++ variable of an Attribute can be shared among other Attributes. This allows the construction of different AttributeLists accessing the same data, thus avoiding the need of copying and bookkeeping. For this reason, the variables in the Attributes are reference counted.
Binding of external data
A user can define Attributes which correspond to variables that are external to the class. This capability facilitates the I/O of complex structures to a database without intermediate data copies.
Sharing of specifications
Attributes and AttributeLists may share specifications. This feature, among other things, reduces the memory consumption of software components which create and destroy such objects rather frequently.

3. Example of usage of the CoralBase API

Examples of usage of the Blob and AttributeList types can be found under the CoralBase unit tests:

4. Implementation specifics

Blob uses the malloc() and realloc() functions of the C standard library in order to ensure the fastest possible contiguous memory allocation.

The Date and TimeStamp classes are simple wrappers of the seal::Time class.

5. Reference documentation of the CoralBase public interfaces