CORAL Component documentation: CoralBase
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
- BLOB The abbreviation for a Binary Large OBject
2. Description of the CoralBase API functionality
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.
types wrap the seal::Time class in order to perform I/O to tables containing DATE and TIMESTAMP columns.
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