casacore
Loading...
Searching...
No Matches
ColumnSet.h
Go to the documentation of this file.
1//# ColumnSet.h: Class to manage a set of table columns
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: casa-feedback@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#ifndef TABLES_COLUMNSET_H
27#define TABLES_COLUMNSET_H
28
29
30//# Includes
31#include <casacore/casa/aips.h>
32#include <casacore/tables/Tables/TableLockData.h>
33#include <casacore/tables/Tables/BaseTable.h>
34#include <casacore/tables/Tables/StorageOption.h>
35#include <casacore/casa/BasicSL/String.h>
36#include <casacore/casa/Arrays/ArrayFwd.h>
37
38#include <map>
39
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42//# Forward Declarations
43class SetupNewTable;
44class Table;
45class TableDesc;
46class TSMOption;
47class BaseTable;
48class TableAttr;
49class ColumnDesc;
50class PlainColumn;
51class DataManager;
52class MultiFile;
53class Record;
54class IPosition;
55class AipsIO;
56
57// <summary>
58// Class to manage a set of table columns
59// </summary>
60
61// <use visibility=local>
62
63// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
64// </reviewed>
65
66// <prerequisite>
67//# Classes you should understand before using this one.
68// <li> PlainTable
69// <li> DataManager
70// </prerequisite>
71
72// <etymology>
73// ColumnSet represent the set of columns in a table.
74// </etymology>
75
76// <synopsis>
77// ColumnSet contains all columns in a plain table (thus not in a RefTable).
78// Furthermore it contains the set of data managers used by the columns
79// in the table.
80//
81// The main purpose of the class is to deal with constructing, writing
82// and reading the column objects. It is used by classes SetupNewTable
83// and Table.
84// </synopsis>
85
86// <todo asof="$DATE:$">
87//# A List of bugs, limitations, extensions or planned refinements.
88// </todo>
89
90
92{
93public:
94
95 // Construct from the table description.
96 // This creates all underlying filled and virtual column objects.
98
100
101 // Reopen the data managers for read/write.
102 void reopenRW();
103
104 // Rename the necessary subtables in the column keywords.
105 void renameTables (const String& newName, const String& oldName);
106
107 // Get the storage option.
109 { return storageOpt_p; }
110
111 // Get the possible MultiFileBase object used to combine files.
112 std::shared_ptr<MultiFileBase> getMultiFile() const
113 { return multiFile_p; }
114
115 // Are subtables used in other processes.
117
118 // Get a column by name.
119 PlainColumn* getColumn (const String& columnName) const;
120
121 // Get a column by index.
122 PlainColumn* getColumn (uInt columnIndex) const;
123
124 // Add a data manager.
125 // It increments seqCount_p and returns that as a unique sequence number.
126 // This can, for instance, be used to create a unique file name.
128
129 // Initialize the data managers for a new table.
130 // It creates the data manager column objects for each column
131 // and it allows the data managers to link themselves to the
132 // Table object and to initialize themselves.
133 void initDataManagers (rownr_t nrrow, Bool bigEndian,
134 const TSMOption& tsmOption,
135 Table& tab);
136
137 // Link the ColumnSet object to the BaseTable object.
138 void linkToTable (BaseTable* baseTableObject);
139
140 // Link the ColumnSet object to the TableLockData object.
141 void linkToLockObject (TableLockData* lockObject);
142
143 // Check if the table is locked for read or write.
144 // If manual or permanent locking is in effect, it checks if the
145 // table is properly locked.
146 // If autolocking is in effect, it locks the table when needed.
147 // <group>
148 void checkReadLock (Bool wait);
149 void checkWriteLock (Bool wait);
150 // </group>
151
152 // Inspect the auto lock when the inspection interval has expired and
153 // release it when another process needs the lock.
154 void autoReleaseLock();
155
156 // If needed, get a temporary user lock.
157 // It returns False if the lock was already there.
159
160 // Release a temporary user lock if the given release flag is True.
161 void userUnlock (Bool releaseFlag);
162
163 // Do all data managers and engines allow to add rows?
165
166 // Do all data managers and engines allow to remove rows?
168
169 // Can the given columns be removed from the data manager?
170 Bool canRemoveColumn (const Vector<String>& columnNames) const;
171
172 // Can a column be renamed in the data manager?
173 Bool canRenameColumn (const String& columnName) const;
174
175 // Add rows to all data managers.
176 void addRow (rownr_t nrrow);
177
178 // Remove a row from all data managers.
179 // It will throw an exception if not possible.
180 void removeRow (rownr_t rownr);
181
182 // Remove the columns from the map and the data manager.
183 void removeColumn (const Vector<String>& columnNames);
184
185 // Rename the column in the map.
186 void renameColumn (const String& newName, const String& oldName);
187
188 // Add a column to the table.
189 // The default implementation throws an "invalid operation" exception.
190 // <group>
191 void addColumn (const ColumnDesc& columnDesc,
192 Bool bigEndian, const TSMOption& tsmOption, Table& tab);
193 void addColumn (const ColumnDesc& columnDesc,
194 const String& dataManager, Bool byName,
195 Bool bigEndian, const TSMOption& tsmOption, Table& tab);
196 void addColumn (const ColumnDesc& columnDesc,
197 const DataManager& dataManager,
198 Bool bigEndian, const TSMOption& tsmOption, Table& tab);
199 void addColumn (const TableDesc& tableDesc,
200 const DataManager& dataManager,
201 Bool bigEndian, const TSMOption& tsmOption, Table& tab);
202 // </group>
203
204 // Get nr of rows.
205 rownr_t nrow() const;
206
207 // Get the actual table description.
209
210 // Get the data manager info.
211 // Optionally only the virtual engines are retrieved.
212 Record dataManagerInfo (Bool virtualOnly=False) const;
213
214 // Get the trace-id of the table.
215 int traceId() const
216 { return baseTablePtr_p->traceId(); }
217
218 // Initialize rows startRownr till endRownr (inclusive).
219 void initialize (rownr_t startRownr, rownr_t endRownr);
220
221 // Write all the data and let the data managers flush their data.
222 // This function is called when a table gets written (i.e. flushed).
223 // It returns True if any data manager wrote something.
224 Bool putFile (Bool writeTable, AipsIO&, const TableAttr&, Bool fsync);
225
226 // Read the data, reconstruct the data managers, and link those to
227 // the table object.
228 // This function gets called when an existing table is read back.
229 // It returns the number of rows in case a data manager thinks there are
230 // more. That is in particular used by LofarStMan.
231 rownr_t getFile (AipsIO&, Table& tab, rownr_t nrrow, Bool bigEndian,
232 const TSMOption& tsmOption);
233
234 // Set the table to being changed.
235 void setTableChanged();
236
237 // Get the data manager change flags (used by PlainTable).
239
240 // Synchronize the data managers when data in them have changed.
241 // It returns the number of rows it think it has, which is needed for
242 // storage managers like LofarStMan.
243 // <src>forceSync=True</src> means that the data managers are forced
244 // to do a sync. Otherwise the contents of the lock file tell if a data
245 // manager has to sync.
246 rownr_t resync (rownr_t nrrow, Bool forceSync);
247
248 // Invalidate the column caches for all columns.
250
251 // Get the correct data manager.
252 // This is used by the column objects to link themselves to the
253 // correct datamanagers when they are read back.
255
256 // Check if no double data manager names have been given.
257 void checkDataManagerNames (const String& tableName) const;
258
259 // Find the data manager with the given name or for the given column.
260 // If the data manager or column is unknown, an exception is thrown.
261 // A blank name means the data manager is unknown.
263 Bool byColumn=False) const;
264
265 // Make a unique data manager name by appending a suffix _n if needed
266 // where n is a number that makes the name unique.
268
269 // Synchronize the columns after it appeared that data in the
270 // main table file have changed.
271 // It cannot deal with changes in number of columns, so it throws an
272 // exception when they have changed.
273 // Keywords in all columns are updated.
274 // The other ColumnSet gives the new data.
275 void syncColumns (const ColumnSet& other, const TableAttr& defaultAttr);
276
277private:
278 // Remove the last data manager (used by addColumn after an exception).
279 // It does the opposite of addDataManager.
281
282 // Let the data managers (from the given index on) initialize themselves.
283 void initSomeDataManagers (uInt from, Table& tab);
284
285 // Let the data managers (from the given index on) prepare themselves.
287
288 // Open or create the MultiFile if needed.
289 void openMultiFile (uInt from, const Table& tab,
291
292 // Check if a data manager name has not already been used.
293 // Start checking at the given index in the array.
294 // It returns False if the name has already been used.
295 // By default an exception is thrown if the name has already been used.
297 const String& tableName,
298 Bool doTthrow=True) const;
299
300 // Do the actual addition of a column.
301 void doAddColumn (const ColumnDesc& columnDesc, DataManager* dataManPtr);
302
303 // Check if columns to be removed can be removed.
304 // It returns a map of DataManager* telling how many columns for
305 // a data manager have to be removed. A count of -1 means that all
306 // columns have to be removed. For such columns the flag in the
307 // returned Block is False, otherwise True.
308 std::map<void*,Int> checkRemoveColumn (const Vector<String>& columnNames);
309
310 // Check if the table is locked for read or write.
311 // If manual or permanent locking is in effect, it checks if the
312 // table is properly locked.
313 // If autolocking is in effect, it locks the table when needed.
315
316
317 //# Declare the variables.
320 std::shared_ptr<MultiFileBase> multiFile_p;
321 rownr_t nrrow_p; //# #rows
323 TableLockData* lockPtr_p; //# lock object
324 std::map<String,void*> colMap_p; //# list of PlainColumns
325 uInt seqCount_p; //# sequence number count
326 //# (used for unique seqnr)
327 Block<void*> blockDataMan_p; //# list of data managers
328 Block<Bool> dataManChanged_p; //# data has changed
329};
330
331
332
334{
335 return nrrow_p;
336}
337inline void ColumnSet::linkToTable (BaseTable* baseTableObject)
338{
339 baseTablePtr_p = baseTableObject;
340}
346{
347 lockPtr_p = lockObject;
348}
350{
353 doLock (FileLocker::Read, wait);
354 }
355}
357{
360 }
361}
362inline void ColumnSet::userUnlock (Bool releaseFlag)
363{
364 if (releaseFlag) {
366 }
367}
369{
371}
376
377
378
379
380} //# NAMESPACE CASACORE - END
381
382#endif
int traceId() const
Get the table's trace-id.
Definition BaseTable.h:492
virtual void setTableChanged()
Set the table to being changed.
simple 1-D array
Definition Block.h:198
OpenOption
Define the possible ByteIO open options.
Definition ByteIO.h:63
void renameTables(const String &newName, const String &oldName)
Rename the necessary subtables in the column keywords.
void removeRow(rownr_t rownr)
Remove a row from all data managers.
Bool canRenameColumn(const String &columnName) const
Can a column be renamed in the data manager?
void autoReleaseLock()
Inspect the auto lock when the inspection interval has expired and release it when another process ne...
Definition ColumnSet.h:368
Bool canAddRow() const
Do all data managers and engines allow to add rows?
BaseTable * baseTablePtr_p
Definition ColumnSet.h:322
void initSomeDataManagers(uInt from, Table &tab)
Let the data managers (from the given index on) initialize themselves.
void linkToTable(BaseTable *baseTableObject)
Link the ColumnSet object to the BaseTable object.
Definition ColumnSet.h:337
void linkToLockObject(TableLockData *lockObject)
Link the ColumnSet object to the TableLockData object.
Definition ColumnSet.h:345
void prepareSomeDataManagers(uInt from)
Let the data managers (from the given index on) prepare themselves.
DataManager * findDataManager(const String &name, Bool byColumn=False) const
Find the data manager with the given name or for the given column.
void removeLastDataManager()
Remove the last data manager (used by addColumn after an exception).
PlainColumn * getColumn(uInt columnIndex) const
Get a column by index.
DataManager * getDataManager(uInt seqnr) const
Get the correct data manager.
Bool userLock(FileLocker::LockType, Bool wait)
If needed, get a temporary user lock.
void addColumn(const TableDesc &tableDesc, const DataManager &dataManager, Bool bigEndian, const TSMOption &tsmOption, Table &tab)
void doAddColumn(const ColumnDesc &columnDesc, DataManager *dataManPtr)
Do the actual addition of a column.
void syncColumns(const ColumnSet &other, const TableAttr &defaultAttr)
Synchronize the columns after it appeared that data in the main table file have changed.
std::map< void *, Int > checkRemoveColumn(const Vector< String > &columnNames)
Check if columns to be removed can be removed.
Bool canRemoveColumn(const Vector< String > &columnNames) const
Can the given columns be removed from the data manager?
void invalidateColumnCaches()
Invalidate the column caches for all columns.
void addColumn(const ColumnDesc &columnDesc, const String &dataManager, Bool byName, Bool bigEndian, const TSMOption &tsmOption, Table &tab)
void removeColumn(const Vector< String > &columnNames)
Remove the columns from the map and the data manager.
void setTableChanged()
Set the table to being changed.
Definition ColumnSet.h:341
std::shared_ptr< MultiFileBase > multiFile_p
Definition ColumnSet.h:320
void checkReadLock(Bool wait)
Check if the table is locked for read or write.
Definition ColumnSet.h:349
TableLockData * lockPtr_p
Definition ColumnSet.h:323
PlainColumn * getColumn(const String &columnName) const
Get a column by name.
Bool putFile(Bool writeTable, AipsIO &, const TableAttr &, Bool fsync)
Write all the data and let the data managers flush their data.
void initDataManagers(rownr_t nrrow, Bool bigEndian, const TSMOption &tsmOption, Table &tab)
Initialize the data managers for a new table.
ColumnSet(TableDesc *, const StorageOption &=StorageOption())
Construct from the table description.
void renameColumn(const String &newName, const String &oldName)
Rename the column in the map.
void checkDataManagerNames(const String &tableName) const
Check if no double data manager names have been given.
void openMultiFile(uInt from, const Table &tab, ByteIO::OpenOption)
Open or create the MultiFile if needed.
rownr_t nrow() const
Get nr of rows.
Definition ColumnSet.h:333
StorageOption storageOpt_p
Definition ColumnSet.h:319
int traceId() const
Get the trace-id of the table.
Definition ColumnSet.h:215
String uniqueDataManagerName(const String &name) const
Make a unique data manager name by appending a suffix _n if needed where n is a number that makes the...
TableDesc actualTableDesc() const
Get the actual table description.
void addColumn(const ColumnDesc &columnDesc, Bool bigEndian, const TSMOption &tsmOption, Table &tab)
Add a column to the table.
void addDataManager(DataManager *)
Add a data manager.
void checkWriteLock(Bool wait)
Definition ColumnSet.h:356
Bool checkDataManagerName(const String &name, uInt from, const String &tableName, Bool doTthrow=True) const
Check if a data manager name has not already been used.
void initialize(rownr_t startRownr, rownr_t endRownr)
Initialize rows startRownr till endRownr (inclusive).
std::shared_ptr< MultiFileBase > getMultiFile() const
Get the possible MultiFileBase object used to combine files.
Definition ColumnSet.h:112
Record dataManagerInfo(Bool virtualOnly=False) const
Get the data manager info.
std::map< String, void * > colMap_p
Definition ColumnSet.h:324
const StorageOption & storageOption() const
Get the storage option.
Definition ColumnSet.h:108
void addColumn(const ColumnDesc &columnDesc, const DataManager &dataManager, Bool bigEndian, const TSMOption &tsmOption, Table &tab)
Block< void * > blockDataMan_p
Definition ColumnSet.h:327
Bool canRemoveRow() const
Do all data managers and engines allow to remove rows?
Block< Bool > & dataManChanged()
Get the data manager change flags (used by PlainTable).
Definition ColumnSet.h:372
Bool areTablesMultiUsed() const
Are subtables used in other processes.
void doLock(FileLocker::LockType, Bool wait)
Check if the table is locked for read or write.
void reopenRW()
Reopen the data managers for read/write.
Block< Bool > dataManChanged_p
Definition ColumnSet.h:328
void addRow(rownr_t nrrow)
Add rows to all data managers.
rownr_t getFile(AipsIO &, Table &tab, rownr_t nrrow, Bool bigEndian, const TSMOption &tsmOption)
Read the data, reconstruct the data managers, and link those to the table object.
TableDesc * tdescPtr_p
Definition ColumnSet.h:318
rownr_t resync(rownr_t nrrow, Bool forceSync)
Synchronize the data managers when data in them have changed.
void userUnlock(Bool releaseFlag)
Release a temporary user lock if the given release flag is True.
Definition ColumnSet.h:362
Abstract base class for a data manager.
LockType
Define the possible lock types.
Definition FileLocker.h:93
@ Write
Acquire a write lock.
Definition FileLocker.h:97
@ Read
Acquire a read lock.
Definition FileLocker.h:95
String: the storage and methods of handling collections of characters.
Definition String.h:223
void autoRelease(Bool always=False)
When the inspection interval has expired, inspect if another process needs the lock.
void release(Bool always=False)
Release the lock.
Bool hasLock(FileLocker::LockType) const
Has this process the read or write lock, thus can the table be read or written safely?
Bool readLocking() const
Is read locking needed?
Definition TableLock.h:187
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:42
unsigned int uInt
Definition aipstype.h:49
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
const Bool True
Definition aipstype.h:41
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:44