SetupNewTab.h

Copying a SetupNewTable object as such is very difficult, if not impossible. However, being able to use a SetupNewTable copy constructor was required to be able to have (static) functions constructing a SetupNewTable object and return it by value (as done for example by ForwardColumn::setupNewTable). Therefore SetupNewTable is implemented using the handle idiom. SetupNewTable is the interface (i.e. the handle) for the user, while underneath SetupNewTableRep is doing all the work. The SetupNewTable copy constructor can simply copy yhe pointer to the underlying SetupNewTableRep object.

To Do

full implementation of tiling

Member Description

SetupNewTableRep (const String& tableName, const String& tableDescName, Table::TableOption)

Create a new table using the table description with the given name. The description will be read from a file.

SetupNewTableRep (const String& tableName, const TableDesc&, Table::TableOption)

Create a new table using the given table description.

~SetupNewTableRep()

uInt& count()

Get access to the reference count.

const String& name() const

Get the name of the table.

int option() const

Get the table create option.

Bool isMarkedForDelete() const

Test if the table is marked for delete.

const TableDesc& tableDesc() const

Get the table description.

void bindColumn (const String& columnName, const DataManager&)

Bind a column to the given data manager. If already bound, the binding will be overwritten. It cannot be used anymore once the SetupNewTableRep object is used to construct a Table object.

void bindColumn (const String& columnName, const String& otherColumn)

Bind a column to the given data manager of the other column. If the other column is not bound, nothing will be done. If columnName is already bound, the binding will be overwritten. It cannot be used anymore once the SetupNewTableRep object is used to construct a Table object.

void bindGroup (const String& columnGroup, const DataManager&, Bool rebind=False)

Bind a group of columns to the given data manager. The flag rebind tells if the binding of an already bound column will be overwritten. It cannot be used anymore once the SetupNewTableRep object is used to construct a Table object.

void bindAll (const DataManager&, Bool rebind=False)

Bind all columns to the given data manager. The flag rebind tells if the binding of an already bound column will be overwritten. It cannot be used anymore once the SetupNewTableRep object is used to construct a Table object.

void bindCreate (const Record& spec)

Create data managers and bind the columns using the specifications in the given record (which is obtained using Table::dataManagerInfo()).

void setShapeColumn (const String& columnName, const IPosition& shape)

Define the shape of fixed shaped arrays in a column. The shape of those arrays has to be known before the table can be constructed. It has to be defined via this function, if it was not already defined in the column description. If only the dimensionality was defined in the column description, the shape's dimensionality must match it. Calling this function for an non-fixed shaped array results in an exception. It cannot be used anymore once the SetupNewTableRep object is used to construct a Table object.

Bool isUsed() const

Test if object is already in use.

ColumnSet* columnSetPtr()

Get pointer to column set. This function is used by PlainTable.

TableDesc* tableDescPtr()

Get pointer to table description. This function is used by PlainTable.

void setInUse()

Set object to in use by a (Plain)Table object. This function is used by PlainTable.

void handleUnbound()

Make a data manager for all unbound columns.

SetupNewTableRep (const SetupNewTableRep&)

Copy constructor is forbidden, because copying a table requires some more knowledge (like table name of result). Declaring it private, makes it unusable.

SetupNewTableRep& operator= (const SetupNewTableRep&)

Assignment is forbidden, because copying a table requires some more knowledge (like table name of result). Declaring it private, makes it unusable.

void setup()

Setup the new table. This checks various things and creates the set of columns.

DataManager* getDataManager (const DataManager& dataMan)

Get the internal data manager object for the given data manager. If it does not exist yet, it will be cloned and stored internally.

class SetupNewTable

Interface

Public Members

SetupNewTable (const String& tableName, const String& tableDescName, Table::TableOption)

SetupNewTable (const String& tableName, const TableDesc&, Table::TableOption)

SetupNewTable (const SetupNewTable&)

~SetupNewTable()

SetupNewTable& operator= (const SetupNewTable&)

const String& name() const

int option() const

Bool isMarkedForDelete() const

const TableDesc& tableDesc() const

void adjustHypercolumns (const SimpleOrderedMap<String, String>& old2new, Bool keepUnknown)

void bindColumn (const String& columnName, const DataManager& dm)

void bindColumn (const String& columnName, const String& otherColumn)

void bindGroup (const String& columnGroup, const DataManager& dm, Bool rebind=False)

void bindAll (const DataManager& dm, Bool rebind=False)

void bindCreate (const Record& spec)

void setShapeColumn (const String& columnName, const IPosition& shape)

Bool isUsed() const

Private Members

ColumnSet* columnSetPtr()

TableDesc* tableDescPtr()

void setInUse()

void handleUnbound()

Description

Review Status

Reviewed By:

bglenden

Date Reviewed:

12AUG94

Programs:

Tests:

None

Prerequisite

TableDesc and related classes like ArrayColumnDesc
DataManager
Table

Etymology

SetupNewTable is a class to setup a new table.

Synopsis

Constructing a new table is a two stage process. First a SetupNewTable object has to be created. Thereafter its columns have to be bound defining how they have to be stored or calculated. Columns have to be bound to a data manager (e.g. a storage manager or a virtual column engine).. Once the required columns are bound, the actual Table object can be created. At this stage, still unbound columns will be bound to the default data managers. The Table object can be used to write data, etc.

The construct options for SetupNewTable are defined in class Table. The possible options are:

New creates a new table file. The Table destructor will write the table into the file.
NewNoReplace as option New, but an exception will be thrown if the table file already exists.
Scratch creates a temporary table. It will be lost when the Table object gets destructed.

More information is provided in the Tables module documentation.

Example

      Table makeIt(const TableDesc &td) {                            // 1
            SetupNewTable maker("test.table", td, Table::New);       // 2
            maker.setShapeColumn("SomeArray", IPosition(2,10,10));   // 3
            maker.setShapeColumn("AnotherArray", IPosition(1,100));  // 4
            StManAipsIO sm1;                                         // 5
            StManKarma  sm2;                                         // 6
            maker.bindAll(sm1);                                      // 7
            maker.bindColumn("SomeCol", sm2);                        // 8
            maker.bindColumn("AnotherCol", sm2);                     // 9
            return Table(maker, 1000); // 1000 row table             // 10
      }                                                              // 11

This code illustrates a simple function that creates a Table starting from a Table descriptor. I

Declare the function makeIt which, given a TableDesc, returns a table.
Create the SetupNewTable object "maker". We want the new table to be named "test.table", its rows columns and keywords come from the TableDesc "td", and this table is to be created unconditionally, that is, it will overwrite an existing table of the same name. Alternative options are given in the synopsis.
Give direct arrays declared in the table descriptor (but not necessarily given a shape) a defined shape; 10x10 for the first array, 100 long vector for the second. If all direct arrays do not have a shape, an error will occur when the table is actually constructed.
Declare two data (storage) managers. AipsIO keeps a whole column in memory, Karma does I/O to keep a subsection in memory at once. A powerful feature of AIPS++ tables is that different columns may be bound to different data managers, which have different properties.
Define the default data manager. AipsIO in this case. Note that this statement and statement 5 are actually not needed. When the Table constructor finds some unbound columns, it will construct the default data manager for them and bind them. A default data manager can be defined in the column description and defaults to AipsIO.
Override the default for some particular columns.
Create and return a 1000 row table. With the Karma storage manager the table size must be defined at construction since new rows can't be added or deleted. If AipsIO was the only storage manager, the size wouldn't need to be defined since rows can be added with AipsIO.

Motivation

In principle, SetupNewTab isn't necessary as what we are doing is logically just constructing a Table, so it could be done in the Table constructor. However such a process can be an involved one - binding multiple data managers and filling in the shapes of direct arrays - so separating the process makes it much clearer what is going on.

To Do

full implementation of tiling

Member Description

SetupNewTable (const String& tableName, const String& tableDescName, Table::TableOption)

Create a new table using the table description with the given name. The description will be read from a file.

SetupNewTable (const String& tableName, const TableDesc&, Table::TableOption)

Create a new table using the given table description.

SetupNewTable (const SetupNewTable&)

Copy constructor (reference semantics).

~SetupNewTable()

SetupNewTable& operator= (const SetupNewTable&)

Assignment (reference semantics).

const String& name() const

Get the name of the table.

int option() const

Get the table create option.

Bool isMarkedForDelete() const

Test if the table is marked for delete.

const TableDesc& tableDesc() const

Get the table description.

void adjustHypercolumns (const SimpleOrderedMap<String, String>& old2new, Bool keepUnknown)

Adjust the hypercolumn definitions. It renames and/or removes columns as necessary.

void bindColumn (const String& columnName, const DataManager& dm)

Bind a column to the given data manager. If already bound, the binding will be overwritten. It cannot be used anymore once the SetupNewTable object is used to construct a Table object.

void bindColumn (const String& columnName, const String& otherColumn)

void bindGroup (const String& columnGroup, const DataManager& dm, Bool rebind=False)

void bindAll (const DataManager& dm, Bool rebind=False)

Bind all columns to the given data manager. The flag rebind tells if the binding of an already bound column will be overwritten. It cannot be used anymore once the SetupNewTable object is used to construct a Table object.

void bindCreate (const Record& spec)

Create data managers and bind the columns using the specifications in the given record (which is obtained using Table::dataManagerInfo()).

void setShapeColumn (const String& columnName, const IPosition& shape)

Bool isUsed() const

Test if object is already in use.

ColumnSet* columnSetPtr()

Get pointer to column set. This function is used by PlainTable.

TableDesc* tableDescPtr()

Get pointer to table description. This function is used by PlainTable.

void setInUse()

Set object to in use by a (Plain)Table object. This function is used by PlainTable.

void handleUnbound()

Make a data manager for all unbound columns.