TableFile Class Reference

Public class that represents a file composed of blocks with tables. More...

`#include <TableFile.h>`

Inheritance diagram for TableFile:
Collaboration diagram for TableFile:

## Public Types

enum | eStatusInd { eCLEAR_STATUS = 0x0000, eDUPLICATE_BLOCKS = 0x0001, eUNNAMED_BLOCKS = 0x0002 }

## Public Member Functions

| TableFile (const Char::eCompareType caseSense=Char::eCASE_SENSITIVE)
| TableFile (const eFileMode fileMode, const string &fileName, const Char::eCompareType caseSense=Char::eCASE_SENSITIVE)
virtual | ~TableFile ()
string | GetFileName (void)
eFileMode | GetFileMode (void)
Char::eCompareType | GetCaseSensitivity (void)
unsigned int | GetStatusInd (void)
unsigned int | GetNumBlocks ()
void | GetBlockNames (vector< string > &blockNames)
string | GetFirstBlockName ()
bool | IsBlockPresent (const string &blockName)
string | AddBlock (const string &blockName)
Block & | GetBlock (const string &blockName)
string | RenameBlock (const string &oldBlockName, const string &newBlockName)
string | RenameFirstBlock (const string &newBlockName)
void | Flush ()
void | Serialize (const string &fileName)
void | Close ()

## Protected Member Functions

void | _SetStatusInd (const string &blockName)
void | _AddBlock (const string &blockName, Serializer *serP)
void | _GetNumTablesInBlocks (vector< UInt32 > &numTablesInBlocks)
ISTable * | _GetTablePtr (const unsigned int blockIndex, const unsigned int tableIndex)
void | _GetAllTables ()
unsigned int | GetTotalNumTables ()
void | GetTableNames (vector< string > &tableNames)
void | GetTablesIndices (vector< unsigned int > &tablesIndices)
void | GetSortedTablesIndices (vector< unsigned int > &tablesIndices)
void | _ReadFileIndex ()
void | _ReadFileIndexVersion0 ()
void | _ReadFileIndexVersion1 ()
void | _WriteFileIndex (Serializer *serP, const vector< unsigned int > &tableLocs)

## Protected Attributes

string | _fileName
eFileMode | _fileMode
Char::eCompareType | _caseSense
unsigned int | _statusInd
mapped_ptr_vector< Block, StringLess > | _blocks
Serializer * | _f

## Detailed Description

Public class that represents a file composed of blocks with tables.

This class represents an ordered container of data blocks. Data blocks can come from DDL, dictionary or CIF files, where each data block is a container of tables. This class provides methods for construction and destruction, data blocks manipulation (addition, retrieval, renaming.). The class does in-memory management of data blocks, as well as serialization and de-serialization to and from a file. The class supports the following file modes: read-only, create, update and virtual. In read-only mode, blocks and tables can only be read (from an existing table file that has been previously serialized to a file) and cannot be modified. Create mode is used to create a table file from scratch and add/update blocks and tables in it and serialize it to a file. Update mode is used to update an existing table file (that has been previously serialized to a file). Virtual mode only provides in-memory management of data blocks and is used when object persistency is not needed. Hence, all modes except virtual mode provide association between in-memory data blocks and persistent data blocks stored in a file.

## Member Enumeration Documentation

## eStatusInd

enum TableFile::eStatusInd

Enumerator
eCLEAR_STATUS |
eDUPLICATE_BLOCKS |
eUNNAMED_BLOCKS |

## Constructor & Destructor Documentation

## TableFile() [1/2]

TableFile::TableFile | ( | const Char::eCompareType | caseSense = `Char::eCASE_SENSITIVE` | ) |

Constructs a table file.

Parameters

  [in] | caseSense | - optional parameter that indicates case sensitivity of table names in blocks. Possible values are case sensitive and case in-sensitive. If not specified, case sensitive table names are assumed.

Returns
  Not applicable

Precondition
  None

Postcondition
  Constructed table file has virtual file mode.

Exceptions

## TableFile() [2/2]

TableFile::TableFile | ( | const eFileMode | fileMode,
|  | const string & | fileName,
|  | const Char::eCompareType | caseSense = `Char::eCASE_SENSITIVE`
| ) |  |

Constructs a table file.

Parameters

  [in] | fileMode | - table file mode. Possible values are read-only, create, update and virtual.
  [in] | fileName | - relative or absolute name of the file where object persistency is maintained. If fileMode specifies virtual mode, this parameter is ignored.
  [in] | caseSense | - optional parameter that indicates case sensitivity of table names in blocks. Possible values are case sensitive and case in-sensitive. If not specified, case sensitive table names are assumed.

Returns
  Not applicable

Precondition
  None

Postcondition
  None

Exceptions

## ~TableFile()

virtual TableFile::~TableFile | ( |  | ) |

virtual

Destructs a table file, by first flushing all the modified tables in data blocks (for create mode or update mode) and then releasing all in-memory objects.

Parameters

  | Not applicable

Returns
  Not applicable

Precondition
  None

Postcondition
  None

Exceptions

## Member Function Documentation

## _AddBlock()

void TableFile::_AddBlock | ( | const string & | blockName,
|  | Serializer * | serP
| ) |  |

protected

## _GetAllTables()

void TableFile::_GetAllTables | ( |  | ) |

protected

## _GetNumTablesInBlocks()

void TableFile::_GetNumTablesInBlocks | ( | vector< UInt32 > & | numTablesInBlocks | ) |

protected

## _GetTablePtr()

ISTable* TableFile::_GetTablePtr | ( | const unsigned int | blockIndex,
|  | const unsigned int | tableIndex
| ) |  |

protected

## _ReadFileIndex()

void TableFile::_ReadFileIndex | ( |  | ) |

protected

## _ReadFileIndexVersion0()

void TableFile::_ReadFileIndexVersion0 | ( |  | ) |

protected

## _ReadFileIndexVersion1()

void TableFile::_ReadFileIndexVersion1 | ( |  | ) |

protected

## _SetStatusInd()

void TableFile::_SetStatusInd | ( | const string & | blockName | ) |

protected

## _WriteFileIndex()

void TableFile::_WriteFileIndex | ( | Serializer * | serP,
|  | const vector< unsigned int > & | tableLocs
| ) |  |

protected

## AddBlock()

string TableFile::AddBlock | ( | const string & | blockName | ) |

Adds a block to the table file. If a block with the specified name already exists, table file stores it under different internal name, that is obtained by appending a "#" symbol and the current block count. After writing blocks, with these kinds of block names, to an ASCII file, "#" symbol becomes a comment and the text after it is ignored. This enables the preservation of all duplicate blocks in the written file.

Parameters

  [in] | blockName | - the name of the data block

Returns
  String that contains the internally assigned data block name. This value is different from blockName, if data block with the name blockName, already exists when this method is invoked.

Precondition
  None

Postcondition
  None

Exceptions

## Close()

void TableFile::Close | ( |  | ) |

Flushes the table file (if in create or update mode) and closes the associated persistent storage file.

Parameters

  | None

Returns
  None

Precondition
  None

Postcondition
  None

Exceptions

## Flush()

void TableFile::Flush | ( |  | ) |

Writes only the new or modified tables in data blocks to the associated persistent storage file (specified at table file construction time).

Parameters

  | None

Returns
  None

Precondition
  Table file must be in create or update mode

Postcondition
  None

Exceptions

  FileModeException | - if table file is not in create or update mode

## GetBlock()

Block& TableFile::GetBlock | ( | const string & | blockName | ) |

Retrieves a reference to the data block in the table file.

Parameters

  [in] | blockName | - the name of the data block

Returns
  Reference to the data block in the table file.

Precondition
  Data block with name blockName must be present

Postcondition
  None

Exceptions

  NotFoundException | - if data block with name blockName does not exist

## GetBlockNames()

void TableFile::GetBlockNames | ( | vector< string > & | blockNames | ) |

Retrieves data block names.

Parameters

  [out] | blockNames | - retrieved data block names

Returns
  None

Precondition
  None

Postcondition
  None

Exceptions

## GetCaseSensitivity()

Char::eCompareType TableFile::GetCaseSensitivity | ( | void |  | ) |

inline

Retrieves case sensitivity of table names in blocks.

Parameters

  | None

Returns
  eCASE_SENSITIVE - if case sensitive
  eCASE_INSENSITIVE - if case in-sensitive

Precondition
  None

Postcondition
  None

Exceptions

References _caseSense.

## GetFileMode()

eFileMode TableFile::GetFileMode | ( | void |  | ) |

inline

Retrieves table file mode.

Parameters

  | None

Returns
  READ_MODE - if read-only mode
  CREATE_MODE - if create mode
  UPDATE_MODE - if update mode
  VIRTUAL_MODE - if virtual mode

Precondition
  None

Postcondition
  None

Exceptions

References _fileMode.

## GetFileName()

string TableFile::GetFileName | ( | void |  | ) |

inline

Retrieves the name of the file that persistently holds data blocks and their tables.

Parameters

  | None

Returns
  String that contains the file name.

Precondition
  None

Postcondition
  None

Exceptions

References _fileName.

## GetFirstBlockName()

string TableFile::GetFirstBlockName | ( |  | ) |

Retrieves the name of the first data block.

Parameters

  | None

Returns
  String that contains the name of the first data block.

Precondition
  None

Postcondition
  None

Exceptions

Referenced by RenameFirstBlock().

## GetNumBlocks()

unsigned int TableFile::GetNumBlocks | ( |  | ) |

inline

Retrieves the number of data blocks in the table file.

Parameters

  | None

Returns
  The number of data blocks in the table file.

Precondition
  None

Postcondition
  None

Exceptions

References _blocks, and mapped_ptr_vector< T, StringCompareT >::size().

## GetSortedTablesIndices()

void TableFile::GetSortedTablesIndices | ( | vector< unsigned int > & | tablesIndices | ) |

protected

## GetStatusInd()

unsigned int TableFile::GetStatusInd | ( | void |  | ) |

inline

Retrieves table file status in form of one or more flags.

Parameters

  | None

Returns
  One or more of these flags:
  eCLEAR_STATUS - no flag value indicates that there are no flags set
  eDUPLICATE_BLOCKS - flag that indicates existence of blocks with the same name, which are internally stored with different names
  eUNNAMED_BLOCKS - flag that indicates existence of blocks with empty names

Precondition
  None

Postcondition
  None

Exceptions

References _statusInd.

## GetTableNames()

void TableFile::GetTableNames | ( | vector< string > & | tableNames | ) |

protected

## GetTablesIndices()

void TableFile::GetTablesIndices | ( | vector< unsigned int > & | tablesIndices | ) |

protected

## GetTotalNumTables()

unsigned int TableFile::GetTotalNumTables | ( |  | ) |

protected

## IsBlockPresent()

bool TableFile::IsBlockPresent | ( | const string & | blockName | ) |

Checks for data block existence.

Parameters

  [in] | blockName | - the name of the data block

Returns
  true - if data block exists
  false - if data block does not exist

Precondition
  None

Postcondition
  None

Exceptions

## RenameBlock()

string TableFile::RenameBlock | ( | const string & | oldBlockName,
|  | const string & | newBlockName
| ) |  |

Changes the data block name.

Parameters

  [in] | oldBlockName | - the name of the data block which is to be renamed
  [in] | newBlockName | - the new data block name

Returns
  String that contains the internally assigned data block name. This value is different from newBlockName, if data block with the name newBlockName, already exists when this method is invoked.

Precondition
  Table file must have at least one data block.
  Data block with name oldBlockName must be present

Postcondition
  None

Exceptions

  EmptyContainerException | - if table file has no data blocks
  NotFoundException | - if data block with name oldBlockName does not exist

Referenced by RenameFirstBlock().

## RenameFirstBlock()

string TableFile::RenameFirstBlock | ( | const string & | newBlockName | ) |

inline

Changes the name of the first data block in table file.

Parameters

  [in] | newBlockName | - the new data block name

Returns
  String that contains the internally assigned data block name. This value is different from newBlockName, if data block with the name newBlockName, already exists when this method is invoked.

Precondition
  Table file must have at least one data block.

Postcondition
  None

Exceptions

  EmptyContainerException | - if table file has no data blocks

References GetFirstBlockName(), and RenameBlock().

## Serialize()

void TableFile::Serialize | ( | const string & | fileName | ) |

Writes all the data blocks and their tables in the specified file. The inteded purpose of this method is to write to a file different than the one specified at construction time.

Parameters

  [in] | fileName | - relative or absolute name of the file

Returns
  None

Precondition
  None

Postcondition
  None

Exceptions

## Member Data Documentation

## _blocks

mapped_ptr_vector<Block, StringLess> TableFile::_blocks

protected

Referenced by GetNumBlocks().

## _caseSense

Char::eCompareType TableFile::_caseSense

protected

Referenced by GetCaseSensitivity().

## _f

Serializer* TableFile::_f

protected

## _fileMode

eFileMode TableFile::_fileMode

protected

Referenced by GetFileMode().

## _fileName

string TableFile::_fileName

protected

Referenced by GetFileName().

## _statusInd

unsigned int TableFile::_statusInd

protected

Referenced by GetStatusInd().

The documentation for this class was generated from the following file:

- rcsb/TableFile.h