casacore
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 
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 //# Forward Declarations
42 class TableDesc;
43 class ColumnSet;
44 class VirtualColumnEngine;
45 class DataManager;
46 class 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 {
95 public:
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 
193 private:
194  // Table name.
196  // Constructor options.
197  int option_p;
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 {
342 friend class PlainTable;
343 friend class MemoryTable;
344 
345 public:
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 
443 private:
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.
Definition: DataManager.h:221
int option() const
Get the table create option.
Definition: SetupNewTab.h:112
void bindColumn(const String &columnName, const String &otherColumn)
Bind a column to the given data manager of the other column.
const CountedPtr< ColumnSet > & columnSetPtr() const
Get pointer to column set.
Definition: SetupNewTab.h:177
Bool delete_p
Marked for delete?
Definition: SetupNewTab.h:200
void bindGroup(const String &columnGroup, const DataManager &, Bool rebind=False)
Bind a group of columns to the given data manager.
const StorageOption & storageOption() const
Get the storage option.
Definition: SetupNewTab.h:116
SetupNewTableRep & operator=(const SetupNewTableRep &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
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
Definition: SetupNewTab.h:203
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.
Definition: SetupNewTab.h:187
CountedPtr< ColumnSet > colSetPtr_p
Definition: SetupNewTab.h:202
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.
StorageOption storageOpt_p
Definition: SetupNewTab.h:198
const CountedPtr< TableDesc > & tableDescPtr() const
Get pointer to table description.
Definition: SetupNewTab.h:182
String tabName_p
Table name.
Definition: SetupNewTab.h:195
const TableDesc & tableDesc() const
Get the table description.
Definition: SetupNewTab.h:124
Bool isMarkedForDelete() const
Test if the table is marked for delete.
Definition: SetupNewTab.h:120
DataManager * getDataManager(const DataManager &dataMan)
Get the internal data manager object for the given data manager.
void handleUnbound()
Make a data manager for all unbound columns.
Bool isUsed() const
Test if object is already in use.
Definition: SetupNewTab.h:172
void setShapeColumn(const String &columnName, const IPosition &shape)
Define the shape of fixed shaped arrays in a column.
CountedPtr< TableDesc > tdescPtr_p
Definition: SetupNewTab.h:201
SetupNewTableRep(const SetupNewTableRep &)
Copy constructor is forbidden, because copying a table requires some more knowledge (like table name ...
const String & name() const
Get the name of the table.
Definition: SetupNewTab.h:108
int option_p
Constructor options.
Definition: SetupNewTab.h:197
Create a new table - define shapes, data managers, etc.
Definition: SetupNewTab.h:341
void bindAll(const DataManager &dm, Bool rebind=False)
Bind all columns to the given data manager.
Definition: SetupNewTab.h:418
CountedPtr< SetupNewTableRep > newTable_p
Actual object.
Definition: SetupNewTab.h:445
const TableDesc & tableDesc() const
Get the table description.
Definition: SetupNewTab.h:380
void bindCreate(const Record &spec)
Create data managers and bind the columns using the specifications in the given record (which is obta...
Definition: SetupNewTab.h:423
const CountedPtr< TableDesc > & tableDescPtr() const
Get pointer to table description.
Definition: SetupNewTab.h:454
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.
Definition: SetupNewTab.h:376
const StorageOption & storageOption() const
Get the storage option.
Definition: SetupNewTab.h:372
void setShapeColumn(const String &columnName, const IPosition &shape)
Define the shape of fixed shaped arrays in a column.
Definition: SetupNewTab.h:436
const CountedPtr< ColumnSet > & columnSetPtr() const
Get pointer to column set.
Definition: SetupNewTab.h:449
void setInUse()
Set object to in use by a (Plain)Table object.
Definition: SetupNewTab.h:459
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.
Definition: SetupNewTab.h:440
int option() const
Get the table create option.
Definition: SetupNewTab.h:368
void bindColumn(const String &columnName, const DataManager &dm)
Bind a column to the given data manager.
Definition: SetupNewTab.h:393
void bindColumn(const String &columnName, const String &otherColumn)
Bind a column to the given data manager of the other column.
Definition: SetupNewTab.h:401
void bindGroup(const String &columnGroup, const DataManager &dm, Bool rebind=False)
Bind a group of columns to the given data manager.
Definition: SetupNewTab.h:409
void handleUnbound()
Make a data manager for all unbound columns.
Definition: SetupNewTab.h:463
void adjustHypercolumns(const std::map< String, String > &old2new, Bool keepUnknown)
Adjust the hypercolumn definitions.
Definition: SetupNewTab.h:385
SetupNewTable & operator=(const SetupNewTable &)
Assignment (reference semantics).
const String & name() const
Get the name of the table.
Definition: SetupNewTab.h:364
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