casacore
ConcatTable.h
Go to the documentation of this file.
1 //# ConcatTable.h: Class to view a concatenation of tables as a single table
2 //# Copyright (C) 2008
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_CONCATTABLE_H
29 #define TABLES_CONCATTABLE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/Tables/BaseTable.h>
35 #include <casacore/tables/Tables/ConcatRows.h>
36 #include <casacore/tables/Tables/TableRecord.h>
37 #include <casacore/tables/Tables/Table.h>
38 #include <casacore/casa/BasicSL/String.h>
39 #include <casacore/casa/Arrays/Vector.h>
40 #include <map>
41 
42 namespace casacore { //# NAMESPACE CASACORE - BEGIN
43 
44  //# Forward Declarations
45  class TSMOption;
46  class ConcatColumn;
47  class AipsIO;
48 
49 
50  // <summary>
51  // Class to view a concatenation of tables as a single table.
52  // </summary>
53 
54  // <use visibility=local>
55 
56  // <reviewed reviewer="UNKNOWN" date="" tests="">
57  // </reviewed>
58 
59  // <prerequisite>
60  //# Classes you should understand before using this one.
61  // <li> BaseTable
62  // <li> ConcatColumn
63  // </prerequisite>
64 
65  // <etymology>
66  // ConcatTable represents the concatenation of one or more tables.
67  // </etymology>
68 
69  // <synopsis>
70  // ConcatTable is used to virtually concatenate one or more tables.
71  // Those tables must have the same description.
72  //
73  // It acts to the user as a normal table. All gets and puts are
74  // handled by ConcatColumn which directs them to the referenced columns
75  // while (if needed) converting the given row number to the row number
76  // in the referenced tables. For that purpose ConcatTable keeps the
77  // number of rows in the referenced tables.
78  // <note>Currently it cannot handle changes in the number of rows in the
79  // underlying tables. </note>
80  //
81  // It is possible to specify the keyword names of the subtables that have
82  // to be concatenated as well. The other subtables are assumed to be
83  // identical for all tables, so only the subtable of the first table is used.
84  //
85  // The ConcatTable maintains its own keyword set, which is initially a copy
86  // of the keyword set of the first table. It replaces the keywords of the
87  // subtables to be concatenated.
88  // The keyword set is not persistent. One can add or change keywords, but
89  // these changes are not kept when the ConcatTable object is made persistent.
90  // </synopsis>
91 
92  // <motivation>
93  // Sometimes a very large MeasurementSet is split into multiple smaller ones
94  // using the time axis. Using ConcatTable they can still be viewed as a
95  // single MS. The SYSCAL subtable is split in time as well, thus it has
96  // to be possible to concatenate that one as well.
97  // <note>An MS split in subband could be concatenated as well provided that
98  // at least the first part contains the full SPECTRAL_WINDOW subtable and
99  // that unique SPWids are used.
100  // </note>
101  // </motivation>
102 
103  // <todo asof="$DATE:$">
104  //# A List of bugs, limitations, extensions or planned refinements.
105  // <li> Maybe not allocating the row number vector for a projection.
106  // This saves space and time, but each rownr conversion will
107  // take a bit more time because it has to test if there is a vector.
108  // <li> Maybe maintain a Vector<String> telling on which columns
109  // the table is ordered. This may speed up selection, but
110  // it is hard to check if the order is changed by a put.
111  // <li> Allow to remove a row or column from the ConcatTable
112  // <li> Allow to rename a column in the ConcatTable
113  // <li> Maybe implement doSort one time for a more efficient sort.
114  // (now everything is handled by BaseTable).
115  // </todo>
116 
117 
118  class ConcatTable : public BaseTable
119  {
120  public:
121 
122  // Create a virtual table as the concatenation of the given tables.
123  // It checks if the table descriptions of the tables are the same.
124  // Subtables with the given names will be concatenated as well.
125  // It is assumed that the other subtables are the same for all tables,
126  // so the ones of the first table are used.
127  // <br>The option can be Table::Old or Table::Update.
128  // <br>If a non-empty subdirectory name is given, the tables will
129  // be moved to that subdirectory when the concatenated table is written
130  // (by writeConcatTable).
131  // <group>
132  ConcatTable (const Block<Table>& tables,
133  const Block<String>& subTables,
134  const String& subDirName);
135  ConcatTable (const Block<String>& tableNames,
136  const Block<String>& subTables,
137  const String& subDirName,
138  int option,
139  const TableLock& lockOptions,
140  const TSMOption& tsmOption);
141  // </group>
142 
143  // Create a concat table out of a file (written by writeConcatTable).
144  // The referenced tables will also be opened (if not stored in the cache).
145  ConcatTable (AipsIO&, const String& name, rownr_t nrrow, int option,
146  const TableLock& lockOptions, const TSMOption& tsmOption);
147 
148  // The destructor flushes (i.e. writes) the table if it is opened
149  // for output and not marked for delete.
150  virtual ~ConcatTable();
151 
152  // Get the names of the tables this table consists of.
153  virtual void getPartNames (Block<String>& names, Bool recursive) const;
154 
155  // Return the layout of a table (i.e. description and #rows).
156  // This function has the advantage that only the minimal amount of
157  // information required is read from the table, thus it is much
158  // faster than a normal table open.
159  // <br> The number of rows is returned. The description of the table
160  // is stored in desc (its contents will be overwritten).
161  static void getLayout (TableDesc& desc, AipsIO& ios);
162 
163  // Try to reopen the table (the underlying ones) for read/write access.
164  // An exception is thrown if the table is not writable.
165  // Nothing is done if the table is already open for read/write.
166  virtual void reopenRW();
167 
168  // Is the table stored in big or little endian format?
169  // It returns the endianness of the first underlying table.
170  virtual Bool asBigEndian() const;
171 
172  // Get the storage option used for the table.
173  // It returns the storage option of the first underlying table.
174  virtual const StorageOption& storageOption() const;
175 
176  // Is the table in use (i.e. open) in another process?
177  // It always returns False.
178  virtual Bool isMultiUsed (Bool checkSubTable) const;
179 
180  // Get the locking info.
181  // All underlying tables have the same lock option.
182  virtual const TableLock& lockOptions() const;
183 
184  // Merge the given lock info with the existing one.
185  virtual void mergeLock (const TableLock& lockOptions);
186 
187  // Has this process the read or write lock, thus can the table
188  // be read or written safely?
190 
191  // Try to lock the table for read or write access.
192  virtual Bool lock (FileLocker::LockType, uInt nattempts);
193 
194  // Unlock the table. This will also synchronize the table data,
195  // thus force the data to be written to disk.
196  virtual void unlock();
197 
198  // Flush the table, i.e. write it to disk.
199  // Nothing will be done if the table is not writable.
200  // A flush can be executed at any time.
201  // When a table is marked for delete, the destructor will remove
202  // files written by intermediate flushes.
203  // Note that if necessary the destructor will do an implicit flush,
204  // unless it is executed due to an exception.
205  virtual void flush (Bool fsync, Bool recursive);
206 
207  // Resync the Table object with the table files.
208  virtual void resync();
209 
210  // Get the modify counter.
211  virtual uInt getModifyCounter() const;
212 
213  // Test if all underlying tables are opened as writable.
214  virtual Bool isWritable() const;
215 
216  // Read a concat table from a file.
217  // The underlying tables will be opened (if not stored in the cache).
218  void getConcat (AipsIO&, int option, const TableLock& lockOptions,
219  const TSMOption& tsmOption);
220 
221  // This is doing a shallow copy.
222  // It gives an error if the ConcatTable has not been stored yet.
223  virtual void copy (const String& newName, int tableOption) const;
224 
225  // Copy the table and all its subtables.
226  // It copies the contents of each row to get a real copy.
227  virtual void deepCopy (const String& newName,
228  const Record& dataManagerInfo,
229  const StorageOption&,
230  int tableOption, Bool, int endianFormat,
231  Bool noRows) const;
232 
233  // It returns the type of the parent table.
234  virtual int tableType() const;
235 
236  // Get the actual table description.
237  virtual TableDesc actualTableDesc() const;
238 
239  // Get the data manager info (of the first underlying table).
240  virtual Record dataManagerInfo() const;
241 
242  // Get readonly access to the table keyword set.
244 
245  // Get read/write access to the table keyword set.
246  // This requires that the table is locked (or it gets locked
247  // when using AutoLocking mode).
249 
250  // Get a column object using its index.
251  virtual BaseColumn* getColumn (uInt columnIndex) const;
252 
253  // Get a column object using its name.
254  virtual BaseColumn* getColumn (const String& columnName) const;
255 
256  // Test if it is possible to remove a row from this table (no).
257  virtual Bool canRemoveRow() const;
258 
259  // Remove the given row.
260  virtual void removeRow (rownr_t rownr);
261 
262  // Test if columns can be removed (no).
263  virtual Bool canRemoveColumn (const Vector<String>& columnNames) const;
264 
265  // Add one or more columns to the table.
266  // The column is added to the parent tables if told so and if not existing.
267  // <group>
268  virtual void addColumn (const ColumnDesc& columnDesc,
269  Bool addToParent);
270  virtual void addColumn (const ColumnDesc& columnDesc,
271  const String& dataManager, Bool byName,
272  Bool addToParent);
273  virtual void addColumn (const ColumnDesc& columnDesc,
274  const DataManager& dataManager,
275  Bool addToParent);
276  virtual void addColumn (const TableDesc& tableDesc,
277  const DataManager& dataManager,
278  Bool addToParent);
279  // </group>
280 
281  // Remove a column.
282  virtual void removeColumn (const Vector<String>& columnNames);
283 
284  // Test if a column can be renamed (no).
285  virtual Bool canRenameColumn (const String& columnName) const;
286 
287  // Rename a column.
288  virtual void renameColumn (const String& newName, const String& oldName);
289 
290  // Rename a hypercolumn.
291  virtual void renameHypercolumn (const String& newName,
292  const String& oldName);
293 
294  // Find the data manager with the given name or for the given column.
295  virtual DataManager* findDataManager (const String& name,
296  Bool byColumn) const;
297 
298  // Get the rows object.
299  const ConcatRows& rows() const
300  { return rows_p; }
301 
302  // Get the column objects in the referenced tables.
304 
305  // Create a (temporary) Table object from it.
307  { return Table (this, False); }
308 
309  private:
310  // Copy constructor is forbidden, because copying a table requires
311  // some more knowledge (like table name of result).
312  // Declaring it private, makes it unusable.
314 
315  // Assignment is forbidden, because copying a table requires
316  // some more knowledge (like table name of result).
317  // Declaring it private, makes it unusable.
319 
320  // Show the extra table structure info (names of used tables).
321  void showStructureExtra (std::ostream&) const;
322 
323  // Open all tables in the required way.
324  void openTables (const Block<String>& tableNames, int option,
325  const TableLock& lockOptions, const TSMOption& tsmOption);
326 
327  // Initialize.
328  // It checks if the descriptions of all tables are equal.
329  // It creates the keyword setfor which it concatenates subtables as needed.
330  void initialize();
331 
332  // Setup the main parts of the object.
333  // <br>First create the name map (mapping column name in ConcatTable to
334  // the column in the original table).
335  // If the BaseTable is a ConcatTable, use its name map.
336  // Otherwise create the initial name map from the table description.
337  // A rename might change the map.
338  // <br>Create the ConcatColumn objects.
339  // <br>Create the initial TableInfo as a copy of the original BaseTable.
340  void setup (BaseTable* btp, const Vector<String>& columnNames);
341 
342  // Add lines containing the concatenated tables to the info.
343  void addInfo();
344 
345  // Create the ConcatColumn objects for all columns in the description.
347 
348  // Handle the subtales that have to be concatenated.
350 
351  // Write a reference table.
352  void writeConcatTable (Bool fsync);
353 
354  // Check if the column can be added, thus does not exist yet.
355  void checkAddColumn (const String& name, Bool addToParent);
356 
357  // Add a column, with internal bookeeping (columns map).
358  void addConcatCol (const ColumnDesc& cd);
359  // Add multiple columns, with internal bookeeping (columns map).
360  void addConcatCol (const TableDesc& tdesc);
361 
362  //# Data members
365  Block<Table> tables_p; //# Tables forming the concat
366  std::map<String,ConcatColumn*> colMap_p; //# map name to column
368  Bool changed_p; //# True = changed since last write
370  };
371 
372 
373 } //# NAMESPACE CASACORE - END
374 
375 #endif
const TableDesc & tableDesc() const
Get the table description.
Definition: BaseTable.h:272
int tableOption() const
Get the table option.
Definition: BaseTable.h:253
simple 1-D array
Definition: Block.h:200
virtual ~ConcatTable()
The destructor flushes (i.e.
void makeConcatCol()
Create the ConcatColumn objects for all columns in the description.
virtual void addColumn(const ColumnDesc &columnDesc, const String &dataManager, Bool byName, Bool addToParent)
virtual BaseColumn * getColumn(const String &columnName) const
Get a column object using its name.
virtual uInt getModifyCounter() const
Get the modify counter.
virtual void renameHypercolumn(const String &newName, const String &oldName)
Rename a hypercolumn.
virtual TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
void initialize()
Initialize.
void setup(BaseTable *btp, const Vector< String > &columnNames)
Setup the main parts of the object.
static void getLayout(TableDesc &desc, AipsIO &ios)
Return the layout of a table (i.e.
virtual void removeColumn(const Vector< String > &columnNames)
Remove a column.
virtual void flush(Bool fsync, Bool recursive)
Flush the table, i.e.
virtual int tableType() const
It returns the type of the parent table.
virtual void renameColumn(const String &newName, const String &oldName)
Rename a column.
virtual void unlock()
Unlock the table.
ConcatTable(AipsIO &, const String &name, rownr_t nrrow, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Create a concat table out of a file (written by writeConcatTable).
virtual void addColumn(const ColumnDesc &columnDesc, const DataManager &dataManager, Bool addToParent)
std::map< String, ConcatColumn * > colMap_p
Definition: ConcatTable.h:366
virtual Bool isWritable() const
Test if all underlying tables are opened as writable.
ConcatTable(const ConcatTable &)
Copy constructor is forbidden, because copying a table requires some more knowledge (like table name ...
void handleSubTables()
Handle the subtales that have to be concatenated.
virtual DataManager * findDataManager(const String &name, Bool byColumn) const
Find the data manager with the given name or for the given column.
ConcatTable(const Block< String > &tableNames, const Block< String > &subTables, const String &subDirName, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Table asTable()
Create a (temporary) Table object from it.
Definition: ConcatTable.h:306
virtual Bool hasLock(FileLocker::LockType) const
Has this process the read or write lock, thus can the table be read or written safely?
virtual void removeRow(rownr_t rownr)
Remove the given row.
virtual Bool asBigEndian() const
Is the table stored in big or little endian format? It returns the endianness of the first underlying...
void showStructureExtra(std::ostream &) const
Show the extra table structure info (names of used tables).
virtual void addColumn(const TableDesc &tableDesc, const DataManager &dataManager, Bool addToParent)
virtual void addColumn(const ColumnDesc &columnDesc, Bool addToParent)
Add one or more columns to the table.
const ConcatRows & rows() const
Get the rows object.
Definition: ConcatTable.h:299
virtual void deepCopy(const String &newName, const Record &dataManagerInfo, const StorageOption &, int tableOption, Bool, int endianFormat, Bool noRows) const
Copy the table and all its subtables.
virtual TableDesc actualTableDesc() const
Get the actual table description.
virtual TableRecord & keywordSet()
Get readonly access to the table keyword set.
ConcatTable & operator=(const ConcatTable &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
void addInfo()
Add lines containing the concatenated tables to the info.
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed (no).
void writeConcatTable(Bool fsync)
Write a reference table.
virtual const StorageOption & storageOption() const
Get the storage option used for the table.
void getConcat(AipsIO &, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Read a concat table from a file.
Block< Table > tables_p
Definition: ConcatTable.h:365
virtual void resync()
Resync the Table object with the table files.
ConcatTable(const Block< Table > &tables, const Block< String > &subTables, const String &subDirName)
Create a virtual table as the concatenation of the given tables.
Block< BaseColumn * > getRefColumns(const String &columnName)
Get the column objects in the referenced tables.
virtual Bool isMultiUsed(Bool checkSubTable) const
Is the table in use (i.e.
virtual void reopenRW()
Try to reopen the table (the underlying ones) for read/write access.
virtual Bool canRemoveRow() const
Test if it is possible to remove a row from this table (no).
virtual Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed (no).
TableRecord keywordSet_p
Definition: ConcatTable.h:367
virtual void mergeLock(const TableLock &lockOptions)
Merge the given lock info with the existing one.
void openTables(const Block< String > &tableNames, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Open all tables in the required way.
void addConcatCol(const TableDesc &tdesc)
Add multiple columns, with internal bookeeping (columns map).
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
virtual void copy(const String &newName, int tableOption) const
This is doing a shallow copy.
void checkAddColumn(const String &name, Bool addToParent)
Check if the column can be added, thus does not exist yet.
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Try to lock the table for read or write access.
Block< String > subTableNames_p
Definition: ConcatTable.h:363
virtual const TableLock & lockOptions() const
Get the locking info.
virtual Record dataManagerInfo() const
Get the data manager info (of the first underlying table).
virtual void getPartNames(Block< String > &names, Bool recursive) const
Get the names of the tables this table consists of.
void addConcatCol(const ColumnDesc &cd)
Add a column, with internal bookeeping (columns map).
Abstract base class for a data manager.
Definition: DataManager.h:221
LockType
Define the possible lock types.
Definition: FileLocker.h:95
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46