casacore
RefTable.h
Go to the documentation of this file.
1 //# RefTable.h: Class for a table as a view of another table
2 //# Copyright (C) 1994,1995,1996,1997,1998,1999,2000,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_REFTABLE_H
29 #define TABLES_REFTABLE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/Tables/BaseTable.h>
35 #include <casacore/casa/BasicSL/String.h>
36 #include <casacore/casa/Arrays/Vector.h>
37 #include <map>
38 
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 //# Forward Declarations
42 class TSMOption;
43 class RefColumn;
44 class AipsIO;
45 
46 
47 // <summary>
48 // Class for a table as a view of another table
49 // </summary>
50 
51 // <use visibility=local>
52 
53 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
54 // </reviewed>
55 
56 // <prerequisite>
57 //# Classes you should understand before using this one.
58 // <li> BaseTable
59 // <li> RefColumn
60 // </prerequisite>
61 
62 // <etymology>
63 // RefTable represents a table which is a view on another table,
64 // thus which references another table.
65 // </etymology>
66 
67 // <synopsis>
68 // RefTable is used to make a view on another table.
69 // Usually it is a view on a subset of the table, either in vertical
70 // or horizontal direction. Thus a subset of rows and/or columns.
71 // It will be the result of a select, sort, project or iterate function.
72 //
73 // It acts to the user as a normal table. All gets and puts are
74 // handled by RefColumn which directs them to the referenced column
75 // while (if needed) converting the given row number to the row number
76 // in the referenced table. For that purpose RefTable maintains a
77 // Vector of the row numbers in the referenced table.
78 //
79 // The RefTable constructor acts in a way that it will always reference
80 // the original table. This means that if a select is done on a RefTable,
81 // the resulting RefTable will also reference the original PlainTable.
82 // This is done to avoid long chains of RefTables.
83 // However, if ever some other kind of table views are introduced
84 // (like a join or a concatenation of similar tables), this cannot be
85 // used anymore. Most software already anticipates on that. The only
86 // exception is the code anding, oring tables (refAnd, etc.).
87 // </synopsis>
88 
89 // <todo asof="$DATE:$">
90 //# A List of bugs, limitations, extensions or planned refinements.
91 // <li> Maybe not allocating the row number vector for a projection.
92 // This saves space and time, but each rownr conversion will
93 // take a bit more time because it has to test if there is a vector.
94 // <li> Maybe maintain a Vector<String> telling on which columns
95 // the table is ordered. This may speed up selection, but
96 // it is hard to check if the order is changed by a put.
97 // <li> Allow to remove a row or column from the RefTable
98 // <li> Allow to rename a column in the RefTable
99 // <li> Maybe implement doSort one time for a more efficient sort.
100 // (now everything is handled by BaseTable).
101 // </todo>
102 
103 
104 class RefTable : public BaseTable
105 {
106 public:
107 
108  // Create a reference table object referencing the
109  // given BaseTable object.
110  // If the BaseTable is actually another RefTable, it will reference
111  // its referenced table (thus the original table) and it will
112  // take its vector of row numbers and projected column names
113  // into account. Thus if a select is done on a projected table,
114  // the resulting RefTable will have the same projection.
115  // <group>
116  // Construct a RefTable with an empty row number vector.
117  // rowOrder=True indicates that the order of the rows will not
118  // be disturbed (as will be the case for a sort).
119  // A row number vector of the given size is initially allocated.
120  // Later this RefTable will be filled in by the select, etc..
121  RefTable (BaseTable*, Bool rowOrder, uInt initialNrrow);
122 
123  // A RefTable with the given row numbers is constructed.
125 
126  // Create a reference table object out of a mask.
127  // The row number vector will consist of the rows for which the
128  // mask has a True value.
129  // The length of the mask must be the number of rows in the BaseTable.
130  RefTable (BaseTable*, const Vector<Bool>& rowMask);
131 
132  // Create a reference table object via projection (i.e. column selection).
133  // The row number vector is a copy of the given table.
134  RefTable (BaseTable*, const Vector<String>& columnNames);
135  // </group>
136 
137  // Create a reference table out of a file (written by writeRefTable).
138  // The referenced table will also be created (if not stored in the cache).
139  RefTable (AipsIO&, const String& name, uInt nrrow, int option,
140  const TableLock& lockOptions, const TSMOption& tsmOption);
141 
142  // The destructor flushes (i.e. writes) the table if it is opened
143  // for output and not marked for delete.
144  virtual ~RefTable();
145 
146  // Return the layout of a table (i.e. description and #rows).
147  // This function has the advantage that only the minimal amount of
148  // information required is read from the table, thus it is much
149  // faster than a normal table open.
150  // <br> The number of rows is returned. The description of the table
151  // is stored in desc (its contents will be overwritten).
152  static void getLayout (TableDesc& desc, AipsIO& ios);
153 
154  // Try to reopen the table (the underlying one) for read/write access.
155  // An exception is thrown if the table is not writable.
156  // Nothing is done if the table is already open for read/write.
157  virtual void reopenRW();
158 
159  // Is the table stored in big or little endian format?
160  virtual Bool asBigEndian() const;
161 
162  // Get the storage option used for the table.
163  virtual const StorageOption& storageOption() const;
164 
165  // Is the table in use (i.e. open) in another process?
166  // It always returns False.
167  virtual Bool isMultiUsed (Bool checkSubTable) const;
168 
169  // Get the locking info.
170  virtual const TableLock& lockOptions() const;
171 
172  // Merge the given lock info with the existing one.
173  virtual void mergeLock (const TableLock& lockOptions);
174 
175  // Has this process the read or write lock, thus can the table
176  // be read or written safely?
177  virtual Bool hasLock (FileLocker::LockType) const;
178 
179  // Try to lock the table for read or write access.
180  virtual Bool lock (FileLocker::LockType, uInt nattempts);
181 
182  // Unlock the table. This will also synchronize the table data,
183  // thus force the data to be written to disk.
184  virtual void unlock();
185 
186  // Flush the table, i.e. write it to disk.
187  // Nothing will be done if the table is not writable.
188  // A flush can be executed at any time.
189  // When a table is marked for delete, the destructor will remove
190  // files written by intermediate flushes.
191  // Note that if necessary the destructor will do an implicit flush,
192  // unless it is executed due to an exception.
193  virtual void flush (Bool fsync, Bool recursive);
194 
195  // Resync the Table object with the table file.
196  virtual void resync();
197 
198  // Get the modify counter.
199  virtual uInt getModifyCounter() const;
200 
201  // Test if the parent table is opened as writable.
202  virtual Bool isWritable() const;
203 
204  // Read a reference table from a file.
205  // The referenced table will also be created (if not stored in the cache).
206  void getRef (AipsIO&, int option, const TableLock& lockOptions,
207  const TSMOption& tsmOption);
208 
209  // This is doing a shallow copy.
210  // It gives an error if the RefTable has not been stored yet.
211  virtual void copy (const String& newName, int tableOption) const;
212 
213  // Copy the table and all its subtables.
214  // It copies the contents of each row to get a real copy.
215  virtual void deepCopy (const String& newName,
216  const Record& dataManagerInfo,
217  const StorageOption&,
218  int tableOption, Bool, int endianFormat,
219  Bool noRows) const;
220 
221  // It returns the type of the parent table.
222  virtual int tableType() const;
223 
224  // Get the actual table description.
225  virtual TableDesc actualTableDesc() const;
226 
227  // Get the data manager info.
228  virtual Record dataManagerInfo() const;
229 
230  // Get readonly access to the table keyword set.
231  virtual TableRecord& keywordSet();
232 
233  // Get read/write access to the table keyword set.
234  // This requires that the table is locked (or it gets locked
235  // when using AutoLocking mode).
236  virtual TableRecord& rwKeywordSet();
237 
238  // Get a column object using its index.
239  virtual BaseColumn* getColumn (uInt columnIndex) const;
240 
241  // Get a column object using its name.
242  virtual BaseColumn* getColumn (const String& columnName) const;
243 
244  // Test if it is possible to remove a row from this table.
245  virtual Bool canRemoveRow() const;
246 
247  // Remove the given row.
248  virtual void removeRow (uInt rownr);
249 
250  // Add one or more columns to the table.
251  // The column is added to the parent table if told so and if not existing.
252  // <group>
253  virtual void addColumn (const ColumnDesc& columnDesc,
254  Bool addToParent);
255  virtual void addColumn (const ColumnDesc& columnDesc,
256  const String& dataManager, Bool byName,
257  Bool addToParent);
258  virtual void addColumn (const ColumnDesc& columnDesc,
259  const DataManager& dataManager,
260  Bool addToParent);
261  virtual void addColumn (const TableDesc& tableDesc,
262  const DataManager& dataManager,
263  Bool addToParent);
264  // </group>
265 
266  // Test if columns can be removed (yes).
267  virtual Bool canRemoveColumn (const Vector<String>& columnNames) const;
268 
269  // Remove columns.
270  virtual void removeColumn (const Vector<String>& columnNames);
271 
272  // Test if a column can be renamed (yes).
273  virtual Bool canRenameColumn (const String& columnName) const;
274 
275  // Rename a column.
276  virtual void renameColumn (const String& newName, const String& oldName);
277 
278  // Rename a hypercolumn.
279  virtual void renameHypercolumn (const String& newName,
280  const String& oldName);
281 
282  // Find the data manager with the given name or for the given column.
283  virtual DataManager* findDataManager (const String& name,
284  Bool byColumn) const;
285 
286  // Get a vector of row numbers.
287  virtual Vector<uInt> rowNumbers() const;
288 
289  // Get parent of this table.
290  virtual BaseTable* root();
291 
292  // Get rownr in root table.
293  // This converts the given row number to the row number in the root table.
294  uInt rootRownr (uInt rownr) const;
295 
296  // Get vector of rownrs in root table.
297  // This converts the given row numbers to row numbers in the root table.
298  Vector<uInt> rootRownr (const Vector<uInt>& rownrs) const;
299 
300  // Tell if the table is in row order.
301  virtual Bool rowOrder() const;
302 
303  // Get row number vector.
304  // This is used by the BaseTable logic and sort routines.
305  virtual Vector<uInt>* rowStorage();
306 
307  // Add a rownr to reference table.
308  void addRownr (uInt rownr);
309 
310  // Set the exact number of rows in the table.
311  // An exception is thrown if more than current nrrow.
312  void setNrrow (uInt nrrow);
313 
314  // Adjust the row numbers to be the actual row numbers in the
315  // root table. This is, for instance, used when a RefTable is sorted.
316  // Optionally it also determines if the resulting rows are in row order.
317  virtual Bool adjustRownrs (uInt nrrow, Vector<uInt>& rownrs,
318  Bool determineOrder) const;
319 
320  // And, or, subtract or xor the row numbers of 2 tables.
321  void refAnd (uInt nr1, const uInt* rows1, uInt nr2, const uInt* rows2);
322  void refOr (uInt nr1, const uInt* rows1, uInt nr2, const uInt* rows2);
323  void refSub (uInt nr1, const uInt* rows1, uInt nr2, const uInt* rows2);
324  void refXor (uInt nr1, const uInt* rows1, uInt nr2, const uInt* rows2);
325  void refNot (uInt nr1, const uInt* rows1, uInt nrmain);
326 
327  // Get the internal pointer in a rowStorage vector.
328  // It checks whether no copy is made of the data.
329  static uInt* getStorage (Vector<uInt>& rownrs);
330 
331 private:
332  BaseTable* baseTabPtr_p; //# pointer to parent table
333  Bool rowOrd_p; //# True = table is in row order
334  Vector<uInt> rowStorage_p; //# row numbers in parent table
335  uInt* rows_p; //# Pointer to rowStorage_p
336  std::map<String,String> nameMap_p; //# map to column name in parent
337  std::map<String,RefColumn*> colMap_p; //# map name to column
338  Bool changed_p; //# True = changed since last write
339 
340  // Copy constructor is forbidden, because copying a table requires
341  // some more knowledge (like table name of result).
342  // Declaring it private, makes it unusable.
343  RefTable (const RefTable&);
344 
345  // Assignment is forbidden, because copying a table requires
346  // some more knowledge (like table name of result).
347  // Declaring it private, makes it unusable.
348  RefTable& operator= (const RefTable&);
349 
350  // Get the names of the tables this table consists of.
351  virtual void getPartNames (Block<String>& names, Bool recursive) const;
352 
353  // Show the extra table structure info (name of root table).
354  void showStructureExtra (std::ostream&) const;
355 
356  // Make a table description for the given columns.
357  static void makeDesc (TableDesc& desc, const TableDesc& rootDesc,
358  std::map<String,String>& nameMap,
359  Vector<String>& names);
360 
361  // Setup the main parts of the object.
362  // <br>First create the name map (mapping column name in RefTable to
363  // the column in the original table).
364  // If the BaseTable is a RefTable, use its name map.
365  // Otherwise create the initial name map from the table description.
366  // A rename might change the map.
367  // <br>Create the RefColumn objects.
368  // <br>Create the initial TableInfo as a copy of the original BaseTable.
369  void setup (BaseTable* btp, const Vector<String>& columnNames);
370 
371  // Create the RefColumn objects for all columns in the description.
372  void makeRefCol();
373 
374  // Write a reference table.
375  void writeRefTable (Bool fsync);
376 
377  // Copy a RefTable that is not persistent. It requires some special logic.
378  void copyRefTable (const String& newName, int tableOption);
379 
380  // Check if a column can be added. Return True if it can and must be
381  // added to the parent table first.
382  Bool checkAddColumn (const String& name, Bool addToParent);
383 
384  // Add a column.
385  void addRefCol (const ColumnDesc& cd);
386  // Add multiple columns.
387  void addRefCol (const TableDesc& tdesc);
388 };
389 
390 
391 
392 inline uInt RefTable::rootRownr (uInt rnr) const
393  { return rows_p[rnr]; }
394 
395 
396 
397 
398 } //# NAMESPACE CASACORE - END
399 
400 #endif
std::map< String, String > nameMap_p
Definition: RefTable.h:336
virtual void flush(Bool fsync, Bool recursive)
Flush the table, i.e.
void showStructureExtra(std::ostream &) const
Show the extra table structure info (name of root table).
virtual void unlock()
Unlock the table.
virtual void removeColumn(const Vector< String > &columnNames)
Remove columns.
const TableDesc & tableDesc() const
Get the table description.
Definition: BaseTable.h:272
virtual Bool canRemoveRow() const
Test if it is possible to remove a row from this table.
virtual TableRecord & keywordSet()
Get readonly access to the table keyword set.
void makeRefCol()
Create the RefColumn objects for all columns in the description.
void writeRefTable(Bool fsync)
Write a reference table.
virtual ~RefTable()
The destructor flushes (i.e.
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
virtual DataManager * findDataManager(const String &name, Bool byColumn) const
Find the data manager with the given name or for the given column.
virtual Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed (yes).
virtual void mergeLock(const TableLock &lockOptions)
Merge the given lock info with the existing one.
Envelope class for the description of a table column.
Definition: ColumnDesc.h:131
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Try to lock the table for read or write access.
Bool checkAddColumn(const String &name, Bool addToParent)
Check if a column can be added.
virtual TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
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.
static uInt * getStorage(Vector< uInt > &rownrs)
Get the internal pointer in a rowStorage vector.
Vector< uInt > rowStorage_p
Definition: RefTable.h:334
virtual Record dataManagerInfo() const
Get the data manager info.
void refNot(uInt nr1, const uInt *rows1, uInt nrmain)
virtual const StorageOption & storageOption() const
Get the storage option used for the table.
int tableOption() const
Get the table option.
Definition: BaseTable.h:253
void setNrrow(uInt nrrow)
Set the exact number of rows in the table.
virtual void renameColumn(const String &newName, const String &oldName)
Rename a column.
virtual Bool adjustRownrs(uInt nrrow, Vector< uInt > &rownrs, Bool determineOrder) const
Adjust the row numbers to be the actual row numbers in the root table.
Options defining how table files are organized.
Definition: StorageOption.h:76
virtual void copy(const String &newName, int tableOption) const
This is doing a shallow copy.
RefTable & operator=(const RefTable &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
void copyRefTable(const String &newName, int tableOption)
Copy a RefTable that is not persistent.
static void getLayout(TableDesc &desc, AipsIO &ios)
Return the layout of a table (i.e.
virtual Vector< uInt > * rowStorage()
Get row number vector.
Abstract base class for tables.
Definition: BaseTable.h:103
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
Class for a table as a view of another table.
Definition: RefTable.h:104
uInt rootRownr(uInt rownr) const
Get rownr in root table.
Definition: RefTable.h:392
void refOr(uInt nr1, const uInt *rows1, uInt nr2, const uInt *rows2)
void setup(BaseTable *btp, const Vector< String > &columnNames)
Setup the main parts of the object.
Options for the Tiled Storage Manager Access.
Definition: TSMOption.h:116
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed (yes).
virtual const TableLock & lockOptions() const
Get the locking info.
virtual int tableType() const
It returns the type of the parent table.
Class to hold table lock options.
Definition: TableLock.h:65
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:182
virtual void renameHypercolumn(const String &newName, const String &oldName)
Rename a hypercolumn.
simple 1-D array
Definition: ArrayIO.h:47
std::map< String, RefColumn * > colMap_p
Definition: RefTable.h:337
void refSub(uInt nr1, const uInt *rows1, uInt nr2, const uInt *rows2)
virtual void removeRow(uInt rownr)
Remove the given row.
Abstract base class for a data manager.
Definition: DataManager.h:224
virtual Vector< uInt > rowNumbers() const
Get a vector of row numbers.
virtual Bool rowOrder() const
Tell if the table is in row order.
virtual Bool isWritable() const
Test if the parent table is opened as writable.
virtual void addColumn(const ColumnDesc &columnDesc, Bool addToParent)
Add one or more columns to the table.
void refAnd(uInt nr1, const uInt *rows1, uInt nr2, const uInt *rows2)
And, or, subtract or xor the row numbers of 2 tables.
virtual Bool isMultiUsed(Bool checkSubTable) const
Is the table in use (i.e.
BaseTable * baseTabPtr_p
Definition: RefTable.h:332
static void makeDesc(TableDesc &desc, const TableDesc &rootDesc, std::map< String, String > &nameMap, Vector< String > &names)
Make a table description for the given columns.
virtual Bool asBigEndian() const
Is the table stored in big or little endian format?
String: the storage and methods of handling collections of characters.
Definition: String.h:223
void addRefCol(const ColumnDesc &cd)
Add a column.
RefTable(BaseTable *, Bool rowOrder, uInt initialNrrow)
Create a reference table object referencing the given BaseTable object.
Define the structure of a Casacore table.
Definition: TableDesc.h:187
virtual Bool hasLock(FileLocker::LockType) const
Has this process the read or write lock, thus can the table be read or written safely?
void refXor(uInt nr1, const uInt *rows1, uInt nr2, const uInt *rows2)
LockType
Define the possible lock types.
Definition: FileLocker.h:95
virtual TableDesc actualTableDesc() const
Get the actual table description.
virtual uInt getModifyCounter() const
Get the modify counter.
virtual BaseTable * root()
Get parent of this table.
void getRef(AipsIO &, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Read a reference table from a file.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
void addRownr(uInt rownr)
Add a rownr to reference table.
unsigned int uInt
Definition: aipstype.h:51
virtual void reopenRW()
Try to reopen the table (the underlying one) for read/write access.
Abstract base class for a table column.
Definition: BaseColumn.h:98
virtual void resync()
Resync the Table object with the table file.
virtual void getPartNames(Block< String > &names, Bool recursive) const
Get the names of the tables this table consists of.