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<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  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.
243  virtual TableRecord& keywordSet();
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).
248  virtual TableRecord& rwKeywordSet();
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 (uInt 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.
303  Block<BaseColumn*> getRefColumns (const String& columnName);
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.
313  ConcatTable (const ConcatTable&);
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.
346  void makeConcatCol();
347 
348  // Handle the subtales that have to be concatenated.
349  void handleSubTables();
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<BaseTable*> baseTabPtr_p; //# pointers to parent tables
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
casacore::ConcatTable::asTable
Table asTable()
Create a (temporary) Table object from it.
Definition: ConcatTable.h:306
casacore::TableDesc
Define the structure of a Casacore table.
Definition: TableDesc.h:187
casacore::ConcatTable::colMap_p
std::map< String, ConcatColumn * > colMap_p
Definition: ConcatTable.h:366
casacore::ConcatTable::lockOptions
virtual const TableLock & lockOptions() const
Get the locking info.
casacore::ConcatTable::subDirName_p
String subDirName_p
Definition: ConcatTable.h:364
casacore::AipsIO
AipsIO is the object persistency mechanism of Casacore
Definition: AipsIO.h:168
casacore::DataManager
Abstract base class for a data manager.
Definition: DataManager.h:224
casacore::ConcatTable::addInfo
void addInfo()
Add lines containing the concatenated tables to the info.
casacore::ConcatTable
Class to view a concatenation of tables as a single table.
Definition: ConcatTable.h:118
casacore::ConcatTable::checkAddColumn
void checkAddColumn(const String &name, Bool addToParent)
Check if the column can be added, thus does not exist yet.
casacore::ConcatTable::showStructureExtra
void showStructureExtra(std::ostream &) const
Show the extra table structure info (names of used tables).
casacore::ConcatTable::storageOption
virtual const StorageOption & storageOption() const
Get the storage option used for the table.
casacore::ConcatTable::findDataManager
virtual DataManager * findDataManager(const String &name, Bool byColumn) const
Find the data manager with the given name or for the given column.
casacore::TableRecord
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:182
casacore::ConcatTable::dataManagerInfo
virtual Record dataManagerInfo() const
Get the data manager info (of the first underlying table).
casacore::ConcatTable::makeConcatCol
void makeConcatCol()
Create the ConcatColumn objects for all columns in the description.
casacore::ConcatTable::setup
void setup(BaseTable *btp, const Vector< String > &columnNames)
Setup the main parts of the object.
casacore::ConcatTable::lock
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Try to lock the table for read or write access.
casacore::FileLocker::LockType
LockType
Define the possible lock types.
Definition: FileLocker.h:95
casacore::ConcatTable::isWritable
virtual Bool isWritable() const
Test if all underlying tables are opened as writable.
casacore::ConcatTable::asBigEndian
virtual Bool asBigEndian() const
Is the table stored in big or little endian format? It returns the endianness of the first underlying...
casacore::ConcatTable::getPartNames
virtual void getPartNames(Block< String > &names, Bool recursive) const
Get the names of the tables this table consists of.
casacore::BaseTable
Abstract base class for tables.
Definition: BaseTable.h:103
casacore::ConcatTable::deepCopy
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.
casacore::ConcatTable::openTables
void openTables(const Block< String > &tableNames, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Open all tables in the required way.
casacore::ConcatTable::getModifyCounter
virtual uInt getModifyCounter() const
Get the modify counter.
casacore::ConcatTable::tableType
virtual int tableType() const
It returns the type of the parent table.
casacore::ConcatTable::unlock
virtual void unlock()
Unlock the table.
casacore::ConcatTable::writeConcatTable
void writeConcatTable(Bool fsync)
Write a reference table.
casacore::BaseTable::tableDesc
const TableDesc & tableDesc() const
Get the table description.
Definition: BaseTable.h:272
casacore::ConcatTable::rows_p
ConcatRows rows_p
Definition: ConcatTable.h:369
casacore::ConcatTable::removeColumn
virtual void removeColumn(const Vector< String > &columnNames)
Remove a column.
casacore::Table
Main interface class to a read/write table.
Definition: Table.h:153
casacore::ConcatTable::ConcatTable
ConcatTable(const Block< BaseTable * > &tables, const Block< String > &subTables, const String &subDirName)
Create a virtual table as the concatenation of the given tables.
casacore::ConcatTable::rwKeywordSet
virtual TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
casacore::BaseColumn
Abstract base class for a table column.
Definition: BaseColumn.h:98
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::ConcatTable::canRemoveColumn
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed (no).
casacore::ConcatTable::renameColumn
virtual void renameColumn(const String &newName, const String &oldName)
Rename a column.
casacore::ConcatTable::getRefColumns
Block< BaseColumn * > getRefColumns(const String &columnName)
Get the column objects in the referenced tables.
casacore::ConcatTable::flush
virtual void flush(Bool fsync, Bool recursive)
Flush the table, i.e.
casacore::ConcatTable::renameHypercolumn
virtual void renameHypercolumn(const String &newName, const String &oldName)
Rename a hypercolumn.
casacore::ConcatTable::operator=
ConcatTable & operator=(const ConcatTable &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
casacore::ConcatTable::keywordSet
virtual TableRecord & keywordSet()
Get readonly access to the table keyword set.
casacore::ConcatTable::getColumn
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
casacore::ConcatTable::canRenameColumn
virtual Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed (no).
casacore::TableLock
Class to hold table lock options.
Definition: TableLock.h:68
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::ConcatTable::addConcatCol
void addConcatCol(const ColumnDesc &cd)
Add a column, with internal bookeeping (columns map).
casacore::ConcatTable::isMultiUsed
virtual Bool isMultiUsed(Bool checkSubTable) const
Is the table in use (i.e.
casacore::ConcatTable::removeRow
virtual void removeRow(uInt rownr)
Remove the given row.
casacore::ConcatTable::mergeLock
virtual void mergeLock(const TableLock &lockOptions)
Merge the given lock info with the existing one.
casacore::ConcatTable::~ConcatTable
virtual ~ConcatTable()
The destructor flushes (i.e.
casacore::ConcatTable::canRemoveRow
virtual Bool canRemoveRow() const
Test if it is possible to remove a row from this table (no).
casacore::ConcatTable::copy
virtual void copy(const String &newName, int tableOption) const
This is doing a shallow copy.
casacore::ConcatTable::resync
virtual void resync()
Resync the Table object with the table files.
casacore::ConcatTable::baseTabPtr_p
Block< BaseTable * > baseTabPtr_p
Definition: ConcatTable.h:365
casacore::ConcatRows
Class holding the row numbers in a ConcatTable.
Definition: ConcatRows.h:83
casacore::ConcatTable::getConcat
void getConcat(AipsIO &, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Read a concat table from a file.
casacore::ConcatTable::actualTableDesc
virtual TableDesc actualTableDesc() const
Get the actual table description.
casacore::ConcatTable::changed_p
Bool changed_p
Definition: ConcatTable.h:368
casacore::TSMOption
Options for the Tiled Storage Manager Access.
Definition: TSMOption.h:116
casacore::BaseTable::tableOption
int tableOption() const
Get the table option.
Definition: BaseTable.h:253
casacore::ConcatTable::keywordSet_p
TableRecord keywordSet_p
Definition: ConcatTable.h:367
casacore::ConcatTable::handleSubTables
void handleSubTables()
Handle the subtales that have to be concatenated.
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::Block
simple 1-D array
Definition: ArrayIO.h:47
casacore::ConcatTable::getLayout
static void getLayout(TableDesc &desc, AipsIO &ios)
Return the layout of a table (i.e.
casacore::Record
A hierarchical collection of named fields of various types.
Definition: Record.h:180
casacore::Vector
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
casacore::ConcatTable::subTableNames_p
Block< String > subTableNames_p
Definition: ConcatTable.h:363
casacore::ConcatTable::reopenRW
virtual void reopenRW()
Try to reopen the table (the underlying ones) for read/write access.
casacore::StorageOption
Options defining how table files are organized.
Definition: StorageOption.h:76
casacore::ConcatTable::rows
const ConcatRows & rows() const
Get the rows object.
Definition: ConcatTable.h:299
casacore::ConcatTable::hasLock
virtual Bool hasLock(FileLocker::LockType) const
Has this process the read or write lock, thus can the table be read or written safely?
casacore::ConcatTable::addColumn
virtual void addColumn(const ColumnDesc &columnDesc, Bool addToParent)
Add one or more columns to the table.
casacore::ColumnDesc
Envelope class for the description of a table column.
Definition: ColumnDesc.h:131
casacore::ConcatTable::initialize
void initialize()
Initialize.