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 <casacore/casa/Containers/SimOrdMap.h>
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 b 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<BaseTable*>& 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, uInt 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?
189  virtual Bool hasLock (FileLocker::LockType) const;
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  int tableOption, Bool, int endianFormat,
230  Bool noRows) const;
231 
232  // It returns the type of the parent table.
233  virtual int tableType() const;
234 
235  // Get the actual table description.
236  virtual TableDesc actualTableDesc() const;
237 
238  // Get the data manager info (of the first underlying table).
239  virtual Record dataManagerInfo() const;
240 
241  // Get readonly access to the table keyword set.
242  virtual TableRecord& keywordSet();
243 
244  // Get read/write access to the table keyword set.
245  // This requires that the table is locked (or it gets locked
246  // when using AutoLocking mode).
247  virtual TableRecord& rwKeywordSet();
248 
249  // Get a column object using its index.
250  virtual BaseColumn* getColumn (uInt columnIndex) const;
251 
252  // Get a column object using its name.
253  virtual BaseColumn* getColumn (const String& columnName) const;
254 
255  // Test if it is possible to remove a row from this table (no).
256  virtual Bool canRemoveRow() const;
257 
258  // Remove the given row.
259  virtual void removeRow (uInt rownr);
260 
261  // Test if columns can be removed (no).
262  virtual Bool canRemoveColumn (const Vector<String>& columnNames) const;
263 
264  // Add one or more columns to the table.
265  // The column is added to the parent tables if told so and if not existing.
266  // <group>
267  virtual void addColumn (const ColumnDesc& columnDesc,
268  Bool addToParent);
269  virtual void addColumn (const ColumnDesc& columnDesc,
270  const String& dataManager, Bool byName,
271  Bool addToParent);
272  virtual void addColumn (const ColumnDesc& columnDesc,
273  const DataManager& dataManager,
274  Bool addToParent);
275  virtual void addColumn (const TableDesc& tableDesc,
276  const DataManager& dataManager,
277  Bool addToParent);
278  // </group>
279 
280  // Remove a column.
281  virtual void removeColumn (const Vector<String>& columnNames);
282 
283  // Test if a column can be renamed (no).
284  virtual Bool canRenameColumn (const String& columnName) const;
285 
286  // Rename a column.
287  virtual void renameColumn (const String& newName, const String& oldName);
288 
289  // Rename a hypercolumn.
290  virtual void renameHypercolumn (const String& newName,
291  const String& oldName);
292 
293  // Find the data manager with the given name or for the given column.
294  virtual DataManager* findDataManager (const String& name,
295  Bool byColumn) const;
296 
297  // Get the rows object.
298  const ConcatRows& rows() const
299  { return rows_p; }
300 
301  // Get the column objects in the referenced tables.
302  Block<BaseColumn*> getRefColumns (const String& columnName);
303 
304  // Create a (temporary) Table object from it.
306  { return Table (this, False); }
307 
308  private:
309  // Copy constructor is forbidden, because copying a table requires
310  // some more knowledge (like table name of result).
311  // Declaring it private, makes it unusable.
312  ConcatTable (const ConcatTable&);
313 
314  // Assignment is forbidden, because copying a table requires
315  // some more knowledge (like table name of result).
316  // Declaring it private, makes it unusable.
318 
319  // Show the extra table structure info (names of used tables).
320  void showStructureExtra (std::ostream&) const;
321 
322  // Open all tables in the required way.
323  void openTables (const Block<String>& tableNames, int option,
324  const TableLock& lockOptions, const TSMOption& tsmOption);
325 
326  // Initialize.
327  // It checks if the descriptions of all tables are equal.
328  // It creates the keyword setfor which it concatenates subtables as needed.
329  void initialize();
330 
331  // Setup the main parts of the object.
332  // <br>First create the name map (mapping column name in ConcatTable to
333  // the column in the original table).
334  // If the BaseTable is a ConcatTable, use its name map.
335  // Otherwise create the initial name map from the table description.
336  // A rename might change the map.
337  // <br>Create the ConcatColumn objects.
338  // <br>Create the initial TableInfo as a copy of the original BaseTable.
339  void setup (BaseTable* btp, const Vector<String>& columnNames);
340 
341  // Add lines containing the concatenated tables to the info.
342  void addInfo();
343 
344  // Create the ConcatColumn objects for all columns in the description.
345  void makeConcatCol();
346 
347  // Handle the subtales that have to be concatenated.
348  void handleSubTables();
349 
350  // Write a reference table.
351  void writeConcatTable (Bool fsync);
352 
353  // Check if the column can be added, thus does not exist yet.
354  void checkAddColumn (const String& name, Bool addToParent);
355 
356  //# Data members
359  Block<BaseTable*> baseTabPtr_p; //# pointers to parent tables
362  Bool changed_p; //# True = changed since last write
364  };
365 
366 
367 } //# NAMESPACE CASACORE - END
368 
369 #endif
Block< String > subTableNames_p
Definition: ConcatTable.h:357
void checkAddColumn(const String &name, Bool addToParent)
Check if the column can be added, thus does not exist yet.
virtual Bool hasLock(FileLocker::LockType) const
Has this process the read or write lock, thus can the table be read or written safely?
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
virtual void addColumn(const ColumnDesc &columnDesc, Bool addToParent)
Add one or more columns to the table.
SimpleOrderedMap< String, ConcatColumn * > colMap_p
Definition: ConcatTable.h:360
const TableDesc & tableDesc() const
Get the table description.
Definition: BaseTable.h:259
void addInfo()
Add lines containing the concatenated tables to the info.
Class holding the row numbers in a ConcatTable.
Definition: ConcatRows.h:83
virtual const StorageOption & storageOption() const
Get the storage option used for the table.
Main interface class to a read/write table.
Definition: Table.h:149
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Try to lock the table for read or write access.
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
virtual const TableLock & lockOptions() const
Get the locking info.
Envelope class for the description of a table column.
Definition: ColumnDesc.h:131
void setup(BaseTable *btp, const Vector< String > &columnNames)
Setup the main parts of the object.
virtual Bool asBigEndian() const
Is the table stored in big or little endian format? It returns the endianness of the first underlying...
virtual DataManager * findDataManager(const String &name, Bool byColumn) const
Find the data manager with the given name or for the given column.
void makeConcatCol()
Create the ConcatColumn objects for all columns in the description.
void showStructureExtra(std::ostream &) const
Show the extra table structure info (names of used tables).
int tableOption() const
Get the table option.
Definition: BaseTable.h:240
virtual void getPartNames(Block< String > &names, Bool recursive) const
Get the names of the tables this table consists of.
virtual void unlock()
Unlock the table.
virtual Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed (no).
Options defining how table files are organized.
Definition: StorageOption.h:71
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed (no).
ConcatTable & operator=(const ConcatTable &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
virtual Bool isMultiUsed(Bool checkSubTable) const
Is the table in use (i.e.
virtual Bool isWritable() const
Test if all underlying tables are opened as writable.
Simple map with keys ordered.
Definition: SimOrdMap.h:69
Abstract base class for tables.
Definition: BaseTable.h:99
virtual ~ConcatTable()
The destructor flushes (i.e.
ConcatTable(const Block< BaseTable *> &tables, const Block< String > &subTables, const String &subDirName)
Create a virtual table as the concatenation of the given tables.
virtual int tableType() const
It returns the type of the parent table.
virtual void copy(const String &newName, int tableOption) const
This is doing a shallow copy.
virtual void renameColumn(const String &newName, const String &oldName)
Rename a column.
void writeConcatTable(Bool fsync)
Write a reference table.
virtual TableRecord & keywordSet()
Get readonly access to the table keyword set.
virtual void deepCopy(const String &newName, const Record &dataManagerInfo, int tableOption, Bool, int endianFormat, Bool noRows) const
Copy the table and all its subtables.
void openTables(const Block< String > &tableNames, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Open all tables in the required way.
virtual void renameHypercolumn(const String &newName, const String &oldName)
Rename a hypercolumn.
virtual uInt getModifyCounter() const
Get the modify counter.
Options for the Tiled Storage Manager Access.
Definition: TSMOption.h:116
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
virtual void removeRow(uInt rownr)
Remove the given row.
A hierarchical collection of named fields of various types.
Definition: Record.h:181
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
virtual void removeColumn(const Vector< String > &columnNames)
Remove a column.
virtual void flush(Bool fsync, Bool recursive)
Flush the table, i.e.
Block< BaseTable * > baseTabPtr_p
Definition: ConcatTable.h:359
virtual Bool canRemoveRow() const
Test if it is possible to remove a row from this table (no).
static void getLayout(TableDesc &desc, AipsIO &ios)
Return the layout of a table (i.e.
virtual TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
const Bool False
Definition: aipstype.h:41
Class to hold table lock options.
Definition: TableLock.h:65
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:182
TableRecord keywordSet_p
Definition: ConcatTable.h:361
simple 1-D array
Definition: ArrayIO.h:47
Block< BaseColumn * > getRefColumns(const String &columnName)
Get the column objects in the referenced tables.
virtual void reopenRW()
Try to reopen the table (the underlying ones) for read/write access.
Abstract base class for a data manager.
Definition: DataManager.h:222
virtual TableDesc actualTableDesc() const
Get the actual table description.
void getConcat(AipsIO &, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Read a concat table from a file.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
const ConcatRows & rows() const
Get the rows object.
Definition: ConcatTable.h:298
virtual void mergeLock(const TableLock &lockOptions)
Merge the given lock info with the existing one.
Table asTable()
Create a (temporary) Table object from it.
Definition: ConcatTable.h:305
void handleSubTables()
Handle the subtales that have to be concatenated.
Define the structure of a Casacore table.
Definition: TableDesc.h:186
virtual void resync()
Resync the Table object with the table files.
LockType
Define the possible lock types.
Definition: FileLocker.h:95
Class to view a concatenation of tables as a single table.
Definition: ConcatTable.h:118
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:48
virtual Record dataManagerInfo() const
Get the data manager info (of the first underlying table).
void initialize()
Initialize.
Abstract base class for a table column.
Definition: BaseColumn.h:98