casacore
Loading...
Searching...
No Matches
SetupNewTab.h
Go to the documentation of this file.
1//# SetupNewTab.h: Create a new table - define shapes, data managers, etc.
2//# Copyright (C) 1994,1995,1996,1999,2001,2002,2003
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef TABLES_SETUPNEWTAB_H
29#define TABLES_SETUPNEWTAB_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/tables/Tables/Table.h>
35#include <casacore/tables/Tables/StorageOption.h>
36#include <casacore/casa/BasicSL/String.h>
37#include <map>
38
39namespace casacore { //# NAMESPACE CASACORE - BEGIN
40
41//# Forward Declarations
42class TableDesc;
43class ColumnSet;
44class VirtualColumnEngine;
45class DataManager;
46class IPosition;
47
48
49// <summary>
50// Representation for handle class SetupNewTable
51// </summary>
52
53// <use visibility=local>
54
55// <reviewed reviewer="bglenden" date="12AUG94" tests="None">
56// </reviewed>
57
58// <prerequisite>
59// <li> TableDesc and related classes like ArrayColumnDesc
60// <li> DataManager
61// <li> Table
62// </prerequisite>
63
64// <etymology>
65// SetupNewTableRep is the representation of class SetupNewTable.
66// </etymology>
67
68// <synopsis>
69// SetupNewTableRep is the representation of class
70// <linkto class="SetupNewTable:description">SetupNewTable</linkto>.
71// Its functionality is described there.
72// </synopsis>
73
74// <motivation>
75// Copying a SetupNewTable object as such is very difficult, if not
76// impossible. However, being able to use a SetupNewTable copy constructor
77// was required to be able to have (static) functions constructing a
78// SetupNewTable object and return it by value (as done for example
79// by <src>ForwardColumn::setupNewTable</src>).
80// Therefore SetupNewTable is implemented using the handle idiom.
81// SetupNewTable is the interface (i.e. the handle) for the user,
82// while underneath SetupNewTableRep is doing all the work.
83// The SetupNewTable copy constructor can simply copy yhe pointer
84// to the underlying SetupNewTableRep object.
85// </motivation>
86
87// <todo asof="$DATE:$">
88//# A List of bugs, limitations, extensions or planned refinements.
89// <li> full implementation of tiling
90// </todo>
91
92
94{
95public:
96 // Create a new table using the table description with the given name.
97 // The description will be read from a file.
98 SetupNewTableRep (const String& tableName, const String& tableDescName,
100
101 // Create a new table using the given table description.
102 SetupNewTableRep (const String& tableName, const TableDesc&,
104
106
107 // Get the name of the table.
108 const String& name() const
109 { return tabName_p; }
110
111 // Get the table create option.
112 int option() const
113 { return option_p; }
114
115 // Get the storage option.
117 { return storageOpt_p; }
118
119 // Test if the table is marked for delete.
121 { return delete_p; }
122
123 // Get the table description.
124 const TableDesc& tableDesc() const
125 { return *tdescPtr_p; }
126
127 // Bind a column to the given data manager.
128 // If already bound, the binding will be overwritten.
129 // It cannot be used anymore once the SetupNewTableRep object is used to
130 // construct a Table object.
131 void bindColumn (const String& columnName, const DataManager&);
132
133 // Bind a column to the given data manager of the other column.
134 // If the other column is not bound, nothing will be done.
135 // If columnName is already bound, the binding will be overwritten.
136 // It cannot be used anymore once the SetupNewTableRep object is used to
137 // construct a Table object.
138 void bindColumn (const String& columnName, const String& otherColumn);
139
140 // Bind a group of columns to the given data manager.
141 // The flag rebind tells if the binding of an already bound column
142 // will be overwritten.
143 // It cannot be used anymore once the SetupNewTableRep object is used to
144 // construct a Table object.
145 void bindGroup (const String& columnGroup, const DataManager&,
146 Bool rebind=False);
147
148 // Bind all columns to the given data manager.
149 // The flag rebind tells if the binding of an already bound column
150 // will be overwritten.
151 // It cannot be used anymore once the SetupNewTableRep object is used to
152 // construct a Table object.
153 void bindAll (const DataManager&, Bool rebind=False);
154
155 // Create data managers and bind the columns using the specifications
156 // in the given record (which is obtained using Table::dataManagerInfo()).
157 void bindCreate (const Record& spec);
158
159 // Define the shape of fixed shaped arrays in a column.
160 // The shape of those arrays has to be known before the table
161 // can be constructed. It has to be defined via this function,
162 // if it was not already defined in the column description.
163 // If only the dimensionality was defined in the column
164 // description, the shape's dimensionality must match it.
165 // Calling this function for an non-fixed shaped array results in
166 // an exception.
167 // It cannot be used anymore once the SetupNewTableRep object is used to
168 // construct a Table object.
169 void setShapeColumn (const String& columnName, const IPosition& shape);
170
171 // Test if object is already in use.
172 Bool isUsed() const
173 { return colSetPtr_p.null(); }
174
175 // Get pointer to column set.
176 // This function is used by PlainTable.
178 { return colSetPtr_p; }
179
180 // Get pointer to table description.
181 // This function is used by PlainTable.
183 { return tdescPtr_p; }
184
185 // Set object to in use by a (Plain)Table object.
186 // This function is used by PlainTable.
187 void setInUse()
188 { colSetPtr_p.reset(); }
189
190 // Make a data manager for all unbound columns.
192
193private:
194 // Table name.
196 // Constructor options.
199 // Marked for delete?
202 CountedPtr<ColumnSet> colSetPtr_p; //# null = object is already used by a Table
203 std::map<void*,void*> dataManMap_p;
204
205 // Copy constructor is forbidden, because copying a table requires
206 // some more knowledge (like table name of result).
207 // Declaring it private, makes it unusable.
209
210 // Assignment is forbidden, because copying a table requires
211 // some more knowledge (like table name of result).
212 // Declaring it private, makes it unusable.
214
215 // Setup the new table.
216 // This checks various things and creates the set of columns.
217 void setup();
218
219 // Get the internal data manager object for the given data manager.
220 // If it does not exist yet, it will be cloned and stored internally.
222};
223
224
225
226
227
228// <summary>
229// Create a new table - define shapes, data managers, etc.
230// </summary>
231
232// <use visibility=export>
233
234// <reviewed reviewer="bglenden" date="12AUG94" tests="None">
235// </reviewed>
236
237// <prerequisite>
238// <li> TableDesc and related classes like ArrayColumnDesc
239// <li> DataManager
240// <li> Table
241// </prerequisite>
242
243// <etymology>
244// SetupNewTable is a class to setup a new table.
245// </etymology>
246
247// <synopsis>
248// Constructing a new table is a two stage process.
249// First a SetupNewTable object has to be created. Thereafter its columns
250// have to be bound defining how they have to be stored or calculated.
251// Columns have to be bound to a data manager (e.g. a storage manager
252// or a virtual column engine)..
253// Once the required columns are bound, the actual Table object can
254// be created. At this stage, still unbound columns will be bound
255// to the default data managers.
256// The Table object can be used to write data, etc.
257//
258// The construct options for SetupNewTable are defined in class Table.
259// The possible options are:
260// <ul>
261// <li> New
262// creates a new table file.
263// The Table destructor will write the table into the file.
264// <li> NewNoReplace
265// as option New, but an exception will be thrown if the table
266// file already exists.
267// <li> Scratch
268// creates a temporary table.
269// It will be lost when the Table object gets destructed.
270// </ul>
271// More information is provided in the Tables module documentation.
272// </synopsis>
273//
274// <example>
275// <srcblock>
276// Table makeIt(const TableDesc &td) { // 1
277// SetupNewTable maker("test.table", td, Table::New); // 2
278// maker.setShapeColumn("SomeArray", IPosition(2,10,10)); // 3
279// maker.setShapeColumn("AnotherArray", IPosition(1,100)); // 4
280// StManAipsIO sm1; // 5
281// StManKarma sm2; // 6
282// maker.bindAll(sm1); // 7
283// maker.bindColumn("SomeCol", sm2); // 8
284// maker.bindColumn("AnotherCol", sm2); // 9
285// return Table(maker, 1000); // 1000 row table // 10
286// } // 11
287// </srcblock>
288// This code illustrates a simple function that creates a Table starting
289// from a Table descriptor. I
290// <ol>
291// <li> Declare the function makeIt which, given a TableDesc, returns
292// a table.
293// <li> Create the SetupNewTable object "maker". We want the new table
294// to be named "test.table", its rows columns and keywords come
295// from the TableDesc "td", and this table is to be created
296// unconditionally, that is, it will overwrite an existing table
297// of the same name. Alternative options are given in the synopsis.
298// <li>
299// <li> Give direct arrays declared in the table descriptor (but not
300// necessarily given a shape) a defined shape; 10x10 for the first
301// array, 100 long vector for the second. If all direct arrays
302// do not have a shape, an error will occur when the table is
303// actually constructed.
304// <li>
305// <li> Declare two data (storage) managers. AipsIO keeps a whole column
306// in memory, Karma does I/O to keep a subsection in memory at once.
307// A powerful feature of Casacore tables is that different columns
308// may be bound to different data managers, which have different
309// properties.
310// <li> Define the default data manager. AipsIO in this case.
311// Note that this statement and statement 5 are actually not
312// needed. When the Table constructor finds some unbound columns,
313// it will construct the default data manager for them and
314// bind them. A default data manager can be defined in the
315// column description and defaults to AipsIO.
316// <li>
317// <li> Override the default for some particular columns.
318// <li> Create and return a 1000 row table. With the Karma storage manager
319// the table size must be defined at construction since new rows
320// can't be added or deleted. If AipsIO was the only storage manager,
321// the size wouldn't need to be defined since rows can be added with
322// AipsIO.
323// </ol>
324// </example>
325
326// <motivation>
327// In principle, SetupNewTab isn't necessary as what we are doing is logically
328// just constructing a Table, so it could be done in the Table constructor.
329// However such a process can be an involved one - binding multiple data
330// managers and filling in the shapes of direct arrays - so separating
331// the process makes it much clearer what is going on.
332// </motivation>
333
334// <todo asof="$DATE:$">
335//# A List of bugs, limitations, extensions or planned refinements.
336// <li> full implementation of tiling
337// </todo>
338
339
341{
342friend class PlainTable;
343friend class MemoryTable;
344
345public:
346 // Create a new table using the table description with the given name.
347 // The description will be read from a file.
348 SetupNewTable (const String& tableName, const String& tableDescName,
350
351 // Create a new table using the given table description.
352 SetupNewTable (const String& tableName, const TableDesc&,
354
355 // Copy constructor (reference semantics).
357
359
360 // Assignment (reference semantics).
362
363 // Get the name of the table.
364 const String& name() const
365 { return newTable_p->name(); }
366
367 // Get the table create option.
368 int option() const
369 { return newTable_p->option(); }
370
371 // Get the storage option.
373 { return newTable_p->storageOption(); }
374
375 // Test if the table is marked for delete.
377 { return newTable_p->isMarkedForDelete(); }
378
379 // Get the table description.
380 const TableDesc& tableDesc() const
381 { return newTable_p->tableDesc(); }
382
383 // Adjust the hypercolumn definitions.
384 // It renames and/or removes columns as necessary.
385 void adjustHypercolumns (const std::map<String, String>& old2new,
386 Bool keepUnknown)
387 { newTable_p->tableDescPtr()->adjustHypercolumns(old2new,keepUnknown); }
388
389 // Bind a column to the given data manager.
390 // If already bound, the binding will be overwritten.
391 // It cannot be used anymore once the SetupNewTable object is used to
392 // construct a Table object.
393 void bindColumn (const String& columnName, const DataManager& dm)
394 { newTable_p->bindColumn (columnName, dm); }
395
396 // Bind a column to the given data manager of the other column.
397 // If the other column is not bound, nothing will be done.
398 // If columnName is already bound, the binding will be overwritten.
399 // It cannot be used anymore once the SetupNewTableRep object is used to
400 // construct a Table object.
401 void bindColumn (const String& columnName, const String& otherColumn)
402 { newTable_p->bindColumn (columnName, otherColumn); }
403
404 // Bind a group of columns to the given data manager.
405 // The flag rebind tells if the binding of an already bound column
406 // will be overwritten.
407 // It cannot be used anymore once the SetupNewTable object is used to
408 // construct a Table object.
409 void bindGroup (const String& columnGroup, const DataManager& dm,
410 Bool rebind=False)
411 { newTable_p->bindGroup (columnGroup, dm, rebind); }
412
413 // Bind all columns to the given data manager.
414 // The flag rebind tells if the binding of an already bound column
415 // will be overwritten.
416 // It cannot be used anymore once the SetupNewTable object is used to
417 // construct a Table object.
418 void bindAll (const DataManager& dm, Bool rebind=False)
419 { newTable_p->bindAll (dm, rebind); }
420
421 // Create data managers and bind the columns using the specifications
422 // in the given record (which is obtained using Table::dataManagerInfo()).
423 void bindCreate (const Record& spec)
424 { newTable_p->bindCreate (spec); }
425
426 // Define the shape of fixed shaped arrays in a column.
427 // The shape of those arrays has to be known before the table
428 // can be constructed. It has to be defined via this function,
429 // if it was not already defined in the column description.
430 // If only the dimensionality was defined in the column
431 // description, the shape's dimensionality must match it.
432 // Calling this function for an non-fixed shaped array results in
433 // an exception.
434 // It cannot be used anymore once the SetupNewTable object is used to
435 // construct a Table object.
436 void setShapeColumn (const String& columnName, const IPosition& shape)
437 { newTable_p->setShapeColumn (columnName, shape); }
438
439 // Test if object is already in use.
440 Bool isUsed() const
441 { return newTable_p->isUsed(); }
442
443private:
444 // Actual object.
446
447 // Get pointer to column set.
448 // This function is used by PlainTable.
450 { return newTable_p->columnSetPtr(); }
451
452 // Get pointer to table description.
453 // This function is used by PlainTable.
455 { return newTable_p->tableDescPtr(); }
456
457 // Set object to in use by a (Plain)Table object.
458 // This function is used by PlainTable.
459 void setInUse()
460 { newTable_p->setInUse(); }
461
462 // Make a data manager for all unbound columns.
464 { newTable_p->handleUnbound(); }
465};
466
467
468
469} //# NAMESPACE CASACORE - END
470
471#endif
Referenced counted pointer for constant data.
Definition CountedPtr.h:81
Abstract base class for a data manager.
const CountedPtr< ColumnSet > & columnSetPtr() const
Get pointer to column set.
int option() const
Get the table create option.
const String & name() const
Get the name of the table.
void bindColumn(const String &columnName, const String &otherColumn)
Bind a column to the given data manager of the other column.
const StorageOption & storageOption() const
Get the storage option.
Bool delete_p
Marked for delete?
void bindGroup(const String &columnGroup, const DataManager &, Bool rebind=False)
Bind a group of columns to the given data manager.
void bindCreate(const Record &spec)
Create data managers and bind the columns using the specifications in the given record (which is obta...
void setup()
Setup the new table.
std::map< void *, void * > dataManMap_p
const TableDesc & tableDesc() const
Get the table description.
SetupNewTableRep(const String &tableName, const TableDesc &, Table::TableOption, const StorageOption &)
Create a new table using the given table description.
void setInUse()
Set object to in use by a (Plain)Table object.
CountedPtr< ColumnSet > colSetPtr_p
void bindAll(const DataManager &, Bool rebind=False)
Bind all columns to the given data manager.
SetupNewTableRep(const String &tableName, const String &tableDescName, Table::TableOption, const StorageOption &)
Create a new table using the table description with the given name.
void bindColumn(const String &columnName, const DataManager &)
Bind a column to the given data manager.
const CountedPtr< TableDesc > & tableDescPtr() const
Get pointer to table description.
String tabName_p
Table name.
Bool isMarkedForDelete() const
Test if the table is marked for delete.
SetupNewTableRep & operator=(const SetupNewTableRep &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
void handleUnbound()
Make a data manager for all unbound columns.
Bool isUsed() const
Test if object is already in use.
void setShapeColumn(const String &columnName, const IPosition &shape)
Define the shape of fixed shaped arrays in a column.
CountedPtr< TableDesc > tdescPtr_p
DataManager * getDataManager(const DataManager &dataMan)
Get the internal data manager object for the given data manager.
SetupNewTableRep(const SetupNewTableRep &)
Copy constructor is forbidden, because copying a table requires some more knowledge (like table name ...
int option_p
Constructor options.
Create a new table - define shapes, data managers, etc.
void bindAll(const DataManager &dm, Bool rebind=False)
Bind all columns to the given data manager.
CountedPtr< SetupNewTableRep > newTable_p
Actual object.
SetupNewTable & operator=(const SetupNewTable &)
Assignment (reference semantics).
void bindCreate(const Record &spec)
Create data managers and bind the columns using the specifications in the given record (which is obta...
const StorageOption & storageOption() const
Get the storage option.
SetupNewTable(const String &tableName, const TableDesc &, Table::TableOption, const StorageOption &=StorageOption())
Create a new table using the given table description.
Bool isMarkedForDelete() const
Test if the table is marked for delete.
void setShapeColumn(const String &columnName, const IPosition &shape)
Define the shape of fixed shaped arrays in a column.
void setInUse()
Set object to in use by a (Plain)Table object.
SetupNewTable(const String &tableName, const String &tableDescName, Table::TableOption, const StorageOption &=StorageOption())
Create a new table using the table description with the given name.
SetupNewTable(const SetupNewTable &)
Copy constructor (reference semantics).
Bool isUsed() const
Test if object is already in use.
const String & name() const
Get the name of the table.
int option() const
Get the table create option.
const CountedPtr< TableDesc > & tableDescPtr() const
Get pointer to table description.
void bindColumn(const String &columnName, const DataManager &dm)
Bind a column to the given data manager.
void bindColumn(const String &columnName, const String &otherColumn)
Bind a column to the given data manager of the other column.
const TableDesc & tableDesc() const
Get the table description.
void bindGroup(const String &columnGroup, const DataManager &dm, Bool rebind=False)
Bind a group of columns to the given data manager.
const CountedPtr< ColumnSet > & columnSetPtr() const
Get pointer to column set.
void handleUnbound()
Make a data manager for all unbound columns.
void adjustHypercolumns(const std::map< String, String > &old2new, Bool keepUnknown)
Adjust the hypercolumn definitions.
String: the storage and methods of handling collections of characters.
Definition String.h:225
TableOption
Define the possible options how a table can be opened.
Definition Table.h:172
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:44
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition ExprNode.h:1987
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42