casacore
Loading...
Searching...
No Matches
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
39namespace casacore { //# NAMESPACE CASACORE - BEGIN
40
41//# Forward Declarations
42class TSMOption;
43class RefColumn;
44class 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
104class RefTable : public BaseTable
105{
106public:
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..
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, rownr_t 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?
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.
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).
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 (rownr_t rownr);
249
250 // Remove the given row.
251 virtual void removeAllRow ();
252
253 // Add one or more columns to the table.
254 // The column is added to the parent table if told so and if not existing.
255 // <group>
256 virtual void addColumn (const ColumnDesc& columnDesc,
257 Bool addToParent);
258 virtual void addColumn (const ColumnDesc& columnDesc,
259 const String& dataManager, Bool byName,
260 Bool addToParent);
261 virtual void addColumn (const ColumnDesc& columnDesc,
262 const DataManager& dataManager,
263 Bool addToParent);
264 virtual void addColumn (const TableDesc& tableDesc,
265 const DataManager& dataManager,
266 Bool addToParent);
267 // </group>
268
269 // Test if columns can be removed (yes).
270 virtual Bool canRemoveColumn (const Vector<String>& columnNames) const;
271
272 // Remove columns.
273 virtual void removeColumn (const Vector<String>& columnNames);
274
275 // Test if a column can be renamed (yes).
276 virtual Bool canRenameColumn (const String& columnName) const;
277
278 // Rename a column.
279 virtual void renameColumn (const String& newName, const String& oldName);
280
281 // Rename a hypercolumn.
282 virtual void renameHypercolumn (const String& newName,
283 const String& oldName);
284
285 // Find the data manager with the given name or for the given column.
286 virtual DataManager* findDataManager (const String& name,
287 Bool byColumn) const;
288
289 // Get a vector of row numbers.
291
292 // Get parent of this table.
293 virtual BaseTable* root();
294
295 // Get rownr in root table.
296 // This converts the given row number to the row number in the root table.
297 rownr_t rootRownr (rownr_t rownr) const;
298
299 // Get vector of rownrs in root table.
300 // This converts the given row numbers to row numbers in the root table.
302
303 // Tell if the table is in row order.
304 virtual Bool rowOrder() const;
305
306 // Get row number vector.
307 // This is used by the BaseTable logic and sort routines.
309
310 // Add a rownr to reference table.
311 void addRownr (rownr_t rownr);
312
313void addRownrRange (rownr_t startRownr, rownr_t endRownr);
314
315 // Set the exact number of rows in the table.
316 // An exception is thrown if more than current nrrow.
317 void setNrrow (rownr_t nrrow);
318
319 // Adjust the row numbers to be the actual row numbers in the
320 // root table. This is, for instance, used when a RefTable is sorted.
321 // Optionally it also determines if the resulting rows are in row order.
322 virtual Bool adjustRownrs (rownr_t nrrow, Vector<rownr_t>& rownrs,
323 Bool determineOrder) const;
324
325 // And, or, subtract or xor the row numbers of 2 tables.
326 void refAnd (rownr_t nr1, const rownr_t* rows1, rownr_t nr2, const rownr_t* rows2);
327 void refOr (rownr_t nr1, const rownr_t* rows1, rownr_t nr2, const rownr_t* rows2);
328 void refSub (rownr_t nr1, const rownr_t* rows1, rownr_t nr2, const rownr_t* rows2);
329 void refXor (rownr_t nr1, const rownr_t* rows1, rownr_t nr2, const rownr_t* rows2);
330 void refNot (rownr_t nr1, const rownr_t* rows1, rownr_t nrmain);
331
332 // Get the internal pointer in a rowStorage vector.
333 // It checks whether no copy is made of the data.
335
336private:
337 BaseTable* baseTabPtr_p; //# pointer to parent table
338 Bool rowOrd_p; //# True = table is in row order
339 Vector<rownr_t> rowStorage_p; //# row numbers in parent table
340 rownr_t* rows_p; //# Pointer to rowStorage_p
341 std::map<String,String> nameMap_p; //# map to column name in parent
342 std::map<String,RefColumn*> colMap_p; //# map name to column
343 Bool changed_p; //# True = changed since last write
344
345 // Copy constructor is forbidden, because copying a table requires
346 // some more knowledge (like table name of result).
347 // Declaring it private, makes it unusable.
349
350 // Assignment is forbidden, because copying a table requires
351 // some more knowledge (like table name of result).
352 // Declaring it private, makes it unusable.
354
355 // Get the names of the tables this table consists of.
356 virtual void getPartNames (Block<String>& names, Bool recursive) const;
357
358 // Show the extra table structure info (name of root table).
359 void showStructureExtra (std::ostream&) const;
360
361 // Make a table description for the given columns.
362 static void makeDesc (TableDesc& desc, const TableDesc& rootDesc,
363 std::map<String,String>& nameMap,
364 Vector<String>& names);
365
366 // Setup the main parts of the object.
367 // <br>First create the name map (mapping column name in RefTable to
368 // the column in the original table).
369 // If the BaseTable is a RefTable, use its name map.
370 // Otherwise create the initial name map from the table description.
371 // A rename might change the map.
372 // <br>Create the RefColumn objects.
373 // <br>Create the initial TableInfo as a copy of the original BaseTable.
374 void setup (BaseTable* btp, const Vector<String>& columnNames);
375
376 // Create the RefColumn objects for all columns in the description.
378
379 // Write a reference table.
380 void writeRefTable (Bool fsync);
381
382 // Copy a RefTable that is not persistent. It requires some special logic.
383 void copyRefTable (const String& newName, int tableOption);
384
385 // Check if a column can be added. Return True if it can and must be
386 // added to the parent table first.
387 Bool checkAddColumn (const String& name, Bool addToParent);
388
389 // Add a column.
390 void addRefCol (const ColumnDesc& cd);
391 // Add multiple columns.
392 void addRefCol (const TableDesc& tdesc);
393};
394
395
396
398 { return rows_p[rnr]; }
399
400
401
402
403} //# NAMESPACE CASACORE - END
404
405#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
Abstract base class for a data manager.
LockType
Define the possible lock types.
Definition FileLocker.h:95
Vector< rownr_t > rowStorage_p
Definition RefTable.h:339
static void getLayout(TableDesc &desc, AipsIO &ios)
Return the layout of a table (i.e.
void refAnd(rownr_t nr1, const rownr_t *rows1, rownr_t nr2, const rownr_t *rows2)
And, or, subtract or xor the row numbers of 2 tables.
void addRownrRange(rownr_t startRownr, rownr_t endRownr)
virtual Record dataManagerInfo() const
Get the data manager info.
virtual Bool canRemoveRow() const
Test if it is possible to remove a row from this table.
virtual DataManager * findDataManager(const String &name, Bool byColumn) const
Find the data manager with the given name or for the given column.
virtual Bool adjustRownrs(rownr_t nrrow, Vector< rownr_t > &rownrs, Bool determineOrder) const
Adjust the row numbers to be the actual row numbers in the root table.
virtual void addColumn(const ColumnDesc &columnDesc, const DataManager &dataManager, Bool addToParent)
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed (yes).
Vector< rownr_t > rootRownr(const Vector< rownr_t > &rownrs) const
Get vector of rownrs in root table.
virtual void unlock()
Unlock the table.
virtual ~RefTable()
The destructor flushes (i.e.
void refSub(rownr_t nr1, const rownr_t *rows1, rownr_t nr2, const rownr_t *rows2)
void showStructureExtra(std::ostream &) const
Show the extra table structure info (name of root table).
static rownr_t * getStorage(Vector< rownr_t > &rownrs)
Get the internal pointer in a rowStorage vector.
virtual void addColumn(const ColumnDesc &columnDesc, const String &dataManager, Bool byName, Bool addToParent)
virtual void removeAllRow()
Remove the given row.
RefTable(BaseTable *, const Vector< rownr_t > &rowNumbers)
A RefTable with the given row numbers is constructed.
RefTable(AipsIO &, const String &name, rownr_t nrrow, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Create a reference table out of a file (written by writeRefTable).
void copyRefTable(const String &newName, int tableOption)
Copy a RefTable that is not persistent.
RefTable & operator=(const RefTable &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
virtual void copy(const String &newName, int tableOption) const
This is doing a shallow copy.
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 Vector< rownr_t > rowNumbers() const
Get a vector of row numbers.
void addRownr(rownr_t rownr)
Add a rownr to reference table.
void makeRefCol()
Create the RefColumn objects for all columns in the description.
std::map< String, String > nameMap_p
Definition RefTable.h:341
virtual TableRecord & keywordSet()
Get readonly access to the table keyword set.
RefTable(BaseTable *, Bool rowOrder, rownr_t initialNrrow)
Create a reference table object referencing the given BaseTable object.
virtual void removeRow(rownr_t rownr)
Remove the given row.
virtual uInt getModifyCounter() const
Get the modify counter.
void addRefCol(const TableDesc &tdesc)
Add multiple columns.
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Try to lock the table for read or write access.
virtual Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed (yes).
rownr_t rootRownr(rownr_t rownr) const
Get rownr in root table.
Definition RefTable.h:397
virtual BaseColumn * getColumn(const String &columnName) const
Get a column object using its name.
void writeRefTable(Bool fsync)
Write a reference table.
void setup(BaseTable *btp, const Vector< String > &columnNames)
Setup the main parts of the object.
RefTable(BaseTable *, const Vector< Bool > &rowMask)
Create a reference table object out of a mask.
virtual void renameHypercolumn(const String &newName, const String &oldName)
Rename a hypercolumn.
rownr_t * rows_p
Definition RefTable.h:340
void refXor(rownr_t nr1, const rownr_t *rows1, rownr_t nr2, const rownr_t *rows2)
virtual const StorageOption & storageOption() const
Get the storage option used for the table.
virtual void getPartNames(Block< String > &names, Bool recursive) const
Get the names of the tables this table consists of.
virtual void addColumn(const ColumnDesc &columnDesc, Bool addToParent)
Add one or more columns to the table.
virtual Bool asBigEndian() const
Is the table stored in big or little endian format?
virtual Vector< rownr_t > * rowStorage()
Get row number vector.
virtual const TableLock & lockOptions() const
Get the locking info.
virtual TableDesc actualTableDesc() const
Get the actual table description.
virtual TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
virtual Bool rowOrder() const
Tell if the table is in row order.
void getRef(AipsIO &, int option, const TableLock &lockOptions, const TSMOption &tsmOption)
Read a reference table from a file.
virtual void mergeLock(const TableLock &lockOptions)
Merge the given lock info with the existing one.
virtual void flush(Bool fsync, Bool recursive)
Flush the table, i.e.
virtual BaseTable * root()
Get parent of this table.
void refOr(rownr_t nr1, const rownr_t *rows1, rownr_t nr2, const rownr_t *rows2)
void addRefCol(const ColumnDesc &cd)
Add a column.
RefTable(const RefTable &)
Copy constructor is forbidden, because copying a table requires some more knowledge (like table name ...
void setNrrow(rownr_t nrrow)
Set the exact number of rows in the table.
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 resync()
Resync the Table object with the table file.
virtual Bool isWritable() const
Test if the parent table is opened as writable.
virtual void renameColumn(const String &newName, const String &oldName)
Rename a column.
static void makeDesc(TableDesc &desc, const TableDesc &rootDesc, std::map< String, String > &nameMap, Vector< String > &names)
Make a table description for the given columns.
std::map< String, RefColumn * > colMap_p
Definition RefTable.h:342
virtual Bool isMultiUsed(Bool checkSubTable) const
Is the table in use (i.e.
void refNot(rownr_t nr1, const rownr_t *rows1, rownr_t nrmain)
RefTable(BaseTable *, const Vector< String > &columnNames)
Create a reference table object via projection (i.e.
BaseTable * baseTabPtr_p
Definition RefTable.h:337
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
virtual void removeColumn(const Vector< String > &columnNames)
Remove columns.
virtual void addColumn(const TableDesc &tableDesc, const DataManager &dataManager, Bool addToParent)
Bool checkAddColumn(const String &name, Bool addToParent)
Check if a column can be added.
virtual void reopenRW()
Try to reopen the table (the underlying one) for read/write access.
virtual int tableType() const
It returns the type of the parent table.
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
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