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 <casacore/casa/Containers/SimOrdMap.h>
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  int tableOption, Bool, int endianFormat,
218  Bool noRows) const;
219 
220  // It returns the type of the parent table.
221  virtual int tableType() const;
222 
223  // Get the actual table description.
224  virtual TableDesc actualTableDesc() const;
225 
226  // Get the data manager info.
227  virtual Record dataManagerInfo() const;
228 
229  // Get readonly access to the table keyword set.
230  virtual TableRecord& keywordSet();
231 
232  // Get read/write access to the table keyword set.
233  // This requires that the table is locked (or it gets locked
234  // when using AutoLocking mode).
235  virtual TableRecord& rwKeywordSet();
236 
237  // Get a column object using its index.
238  virtual BaseColumn* getColumn (uInt columnIndex) const;
239 
240  // Get a column object using its name.
241  virtual BaseColumn* getColumn (const String& columnName) const;
242 
243  // Test if it is possible to remove a row from this table.
244  virtual Bool canRemoveRow() const;
245 
246  // Remove the given row.
247  virtual void removeRow (uInt rownr);
248 
249  // Add one or more columns to the table.
250  // The column is added to the parent table if told so and if not existing.
251  // <group>
252  virtual void addColumn (const ColumnDesc& columnDesc,
253  Bool addToParent);
254  virtual void addColumn (const ColumnDesc& columnDesc,
255  const String& dataManager, Bool byName,
256  Bool addToParent);
257  virtual void addColumn (const ColumnDesc& columnDesc,
258  const DataManager& dataManager,
259  Bool addToParent);
260  virtual void addColumn (const TableDesc& tableDesc,
261  const DataManager& dataManager,
262  Bool addToParent);
263  // </group>
264 
265  // Test if columns can be removed (yes).
266  virtual Bool canRemoveColumn (const Vector<String>& columnNames) const;
267 
268  // Remove columns.
269  virtual void removeColumn (const Vector<String>& columnNames);
270 
271  // Test if a column can be renamed (yes).
272  virtual Bool canRenameColumn (const String& columnName) const;
273 
274  // Rename a column.
275  virtual void renameColumn (const String& newName, const String& oldName);
276 
277  // Rename a hypercolumn.
278  virtual void renameHypercolumn (const String& newName,
279  const String& oldName);
280 
281  // Find the data manager with the given name or for the given column.
282  virtual DataManager* findDataManager (const String& name,
283  Bool byColumn) const;
284 
285  // Get a vector of row numbers.
286  virtual Vector<uInt> rowNumbers() const;
287 
288  // Get parent of this table.
289  virtual BaseTable* root();
290 
291  // Get rownr in root table.
292  // This converts the given row number to the row number in the root table.
293  uInt rootRownr (uInt rownr) const;
294 
295  // Get vector of rownrs in root table.
296  // This converts the given row numbers to row numbers in the root table.
297  Vector<uInt> rootRownr (const Vector<uInt>& rownrs) const;
298 
299  // Tell if the table is in row order.
300  virtual Bool rowOrder() const;
301 
302  // Get row number vector.
303  // This is used by the BaseTable logic and sort routines.
304  virtual Vector<uInt>* rowStorage();
305 
306  // Add a rownr to reference table.
307  void addRownr (uInt rownr);
308 
309  // Set the exact number of rows in the table.
310  // An exception is thrown if more than current nrrow.
311  void setNrrow (uInt nrrow);
312 
313  // Adjust the row numbers to be the actual row numbers in the
314  // root table. This is, for instance, used when a RefTable is sorted.
315  // Optionally it also determines if the resulting rows are in row order.
316  virtual Bool adjustRownrs (uInt nrrow, Vector<uInt>& rownrs,
317  Bool determineOrder) const;
318 
319  // And, or, subtract or xor the row numbers of 2 tables.
320  void refAnd (uInt nr1, const uInt* rows1, uInt nr2, const uInt* rows2);
321  void refOr (uInt nr1, const uInt* rows1, uInt nr2, const uInt* rows2);
322  void refSub (uInt nr1, const uInt* rows1, uInt nr2, const uInt* rows2);
323  void refXor (uInt nr1, const uInt* rows1, uInt nr2, const uInt* rows2);
324  void refNot (uInt nr1, const uInt* rows1, uInt nrmain);
325 
326  // Get the internal pointer in a rowStorage vector.
327  // It checks whether no copy is made of the data.
328  static uInt* getStorage (Vector<uInt>& rownrs);
329 
330 private:
331  BaseTable* baseTabPtr_p; //# pointer to parent table
332  Bool rowOrd_p; //# True = table is in row order
333  Vector<uInt> rowStorage_p; //# row numbers in parent table
334  uInt* rows_p; //# Pointer to rowStorage_p
335  SimpleOrderedMap<String,String> nameMap_p; //# map to column name in parent
337  Bool changed_p; //# True = changed since last write
338 
339  // Copy constructor is forbidden, because copying a table requires
340  // some more knowledge (like table name of result).
341  // Declaring it private, makes it unusable.
342  RefTable (const RefTable&);
343 
344  // Assignment is forbidden, because copying a table requires
345  // some more knowledge (like table name of result).
346  // Declaring it private, makes it unusable.
347  RefTable& operator= (const RefTable&);
348 
349  // Get the names of the tables this table consists of.
350  virtual void getPartNames (Block<String>& names, Bool recursive) const;
351 
352  // Show the extra table structure info (name of root table).
353  void showStructureExtra (std::ostream&) const;
354 
355  // Make a table description for the given columns.
356  static void makeDesc (TableDesc& desc, const TableDesc& rootDesc,
358  Vector<String>& names);
359 
360  // Setup the main parts of the object.
361  // <br>First create the name map (mapping column name in RefTable to
362  // the column in the original table).
363  // If the BaseTable is a RefTable, use its name map.
364  // Otherwise create the initial name map from the table description.
365  // A rename might change the map.
366  // <br>Create the RefColumn objects.
367  // <br>Create the initial TableInfo as a copy of the original BaseTable.
368  void setup (BaseTable* btp, const Vector<String>& columnNames);
369 
370  // Create the RefColumn objects for all columns in the description.
371  void makeRefCol();
372 
373  // Write a reference table.
374  void writeRefTable (Bool fsync);
375 
376  // Copy a RefTable that is not persistent. It requires some special logic.
377  void copyRefTable (const String& newName, int tableOption);
378 
379  // Check if a column can be added. Return True if it can and must be
380  // added to the parent table first.
381  Bool checkAddColumn (const String& name, Bool addToParent);
382 
383  // Add a column.
384  void addRefCol (const ColumnDesc& cd);
385  // Add multiple columns.
386  void addRefCol (const TableDesc& tdesc);
387 };
388 
389 
390 
391 inline uInt RefTable::rootRownr (uInt rnr) const
392  { return rows_p[rnr]; }
393 
394 
395 
396 
397 } //# NAMESPACE CASACORE - END
398 
399 #endif
uInt rootRownr(uInt rownr) const
Get rownr in root table.
Definition: RefTable.h:391
virtual void flush(Bool fsync, Bool recursive)
Flush the table, i.e.
virtual void unlock()
Unlock the table.
virtual const StorageOption & storageOption() const
Get the storage option used for the table.
virtual void removeColumn(const Vector< String > &columnNames)
Remove columns.
virtual Bool canRemoveRow() const
Test if it is possible to remove a row from this table.
int tableOption() const
Get the table option.
Definition: BaseTable.h:240
void showStructureExtra(std::ostream &) const
Show the extra table structure info (name of root 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.
virtual Vector< uInt > rowNumbers() const
Get a vector of row numbers.
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.
virtual uInt getModifyCounter() const
Get the modify counter.
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
virtual const TableLock & lockOptions() const
Get the locking info.
virtual Bool isMultiUsed(Bool checkSubTable) const
Is the table in use (i.e.
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 void copy(const String &newName, int tableOption) const
This is doing a shallow copy.
virtual TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
static uInt * getStorage(Vector< uInt > &rownrs)
Get the internal pointer in a rowStorage vector.
Vector< uInt > rowStorage_p
Definition: RefTable.h:333
virtual Bool asBigEndian() const
Is the table stored in big or little endian format?
virtual Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed (yes).
static void makeDesc(TableDesc &desc, const TableDesc &rootDesc, SimpleOrderedMap< String, String > &nameMap, Vector< String > &names)
Make a table description for the given columns.
void refNot(uInt nr1, const uInt *rows1, uInt nrmain)
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed (yes).
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 setNrrow(uInt nrrow)
Set the exact number of rows in the table.
virtual void renameColumn(const String &newName, const String &oldName)
Rename a column.
Options defining how table files are organized.
Definition: StorageOption.h:71
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.
Simple map with keys ordered.
Definition: SimOrdMap.h:69
virtual DataManager * findDataManager(const String &name, Bool byColumn) const
Find the data manager with the given name or for the given column.
Abstract base class for tables.
Definition: BaseTable.h:99
Class for a table as a view of another table.
Definition: RefTable.h:104
virtual Bool isWritable() const
Test if the parent table is opened as writable.
void refOr(uInt nr1, const uInt *rows1, uInt nr2, const uInt *rows2)
virtual Bool rowOrder() const
Tell if the table is in row order.
void setup(BaseTable *btp, const Vector< String > &columnNames)
Setup the main parts of the object.
virtual void getPartNames(Block< String > &names, Bool recursive) const
Get the names of the tables this table consists of.
Options for the Tiled Storage Manager Access.
Definition: TSMOption.h:116
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 TableDesc actualTableDesc() const
Get the actual table description.
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
SimpleOrderedMap< String, RefColumn * > colMap_p
Definition: RefTable.h:336
void refSub(uInt nr1, const uInt *rows1, uInt nr2, const uInt *rows2)
virtual void removeRow(uInt rownr)
Remove the given row.
SimpleOrderedMap< String, String > nameMap_p
Definition: RefTable.h:335
Abstract base class for a data manager.
Definition: DataManager.h:222
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.
BaseTable * baseTabPtr_p
Definition: RefTable.h:331
virtual Bool hasLock(FileLocker::LockType) const
Has this process the read or write lock, thus can the table be read or written safely?
String: the storage and methods of handling collections of characters.
Definition: String.h:223
void addRefCol(const ColumnDesc &cd)
Add a column.
virtual Record dataManagerInfo() const
Get the data manager info.
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:186
void refXor(uInt nr1, const uInt *rows1, uInt nr2, const uInt *rows2)
LockType
Define the possible lock types.
Definition: FileLocker.h:95
const TableDesc & tableDesc() const
Get the table description.
Definition: BaseTable.h:259
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:48
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.