casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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
uInt rootRownr(uInt rownr) const
Get rownr in root table.
Definition: RefTable.h:392
std::map< String, String > nameMap_p
Definition: RefTable.h:336
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:253
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.
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.
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:334
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).
void refNot(uInt nr1, const uInt *rows1, uInt nrmain)
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
ABSTRACT CLASSES Abstract class for colors Any implementation of color should be able to provide a hexadecimal form of the if a human readable name(i.e."black").In many places throughout the plotter
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed (yes).
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:76
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.
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:103
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:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
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
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 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: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 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:187
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:272
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.
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
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42
virtual void resync()
Resync the Table object with the table file.