casacore
PlainTable.h
Go to the documentation of this file.
1 //# PlainTable.h: Class defining a plain regular 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_PLAINTABLE_H
29 #define TABLES_PLAINTABLE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/Tables/BaseTable.h>
35 #include <casacore/tables/Tables/TableCache.h>
36 #include <casacore/tables/Tables/TableRecord.h>
37 #include <casacore/tables/Tables/TableSyncData.h>
38 #include <casacore/tables/DataMan/TSMOption.h>
39 #include <casacore/casa/IO/AipsIO.h>
40 
41 namespace casacore { //# NAMESPACE CASACORE - BEGIN
42 
43 //# Forward Declarations
44 class SetupNewTable;
45 class TableLock;
46 class TableLockData;
47 class ColumnSet;
48 class IPosition;
49 class AipsIO;
50 class MemoryIO;
51 
52 
53 // <summary>
54 // Class defining a plain regular table
55 // </summary>
56 
57 // <use visibility=local>
58 
59 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
60 // </reviewed>
61 
62 // <prerequisite>
63 //# Classes you should understand before using this one.
64 // <li> BaseTable
65 // <li> BaseColumn
66 // </prerequisite>
67 
68 // <etymology>
69 // PlainTable represents a plain regular table. This is opposed to a
70 // RefTable, which is a view on a PlainTable.
71 // </etymology>
72 
73 // <synopsis>
74 // PlainTable is a table consisting of a keyword set and a number of
75 // filled and virtual columns. The table control information and the
76 // keyword set is stored in an AipsIO file. The data in the filled columns
77 // are stored separately by storage managers.
78 // </synopsis>
79 
80 // <todo asof="$DATE:$">
81 //# A List of bugs, limitations, extensions or planned refinements.
82 // <li> notify RefTable's when deleting rows
83 // </todo>
84 
85 class PlainTable : public BaseTable
86 {
87 public:
88 
89  // Construct the object for a new table.
90  // It creates storage manager(s) for unbound columns and initializes
91  // all storage managers. The given number of rows is stored in
92  // the table and initialized if the flag is set.
93  PlainTable (SetupNewTable&, uInt nrrow, Bool initialize,
94  const TableLock& lockOptions, int endianFormat,
95  const TSMOption& tsmOption);
96 
97 #ifdef HAVE_MPI
98  // MPI version of the constructor
99  PlainTable (MPI_Comm mpiComm, SetupNewTable&, uInt nrrow,
100  Bool initialize, const TableLock& lockOptions,
101  int endianFormat, const TSMOption& tsmOption);
102 #endif
103 
104  // Common part of the constructor shared by MPI and non-MPI
105  void PlainTableCommon (SetupNewTable&, uInt nrrow, Bool initialize,
106  const TableLock& lockOptions, int endianFormat,
107  const TSMOption& tsmOption);
108 
109  // Construct the object for an existing table.
110  // It opens the table file, reads the table control information
111  // and creates and initializes the required storage managers.
112  PlainTable (AipsIO&, uInt version, const String& name, const String& type,
113  uInt nrrow, int option, const TableLock& lockOptions,
114  const TSMOption& tsmOption, Bool addToCache, uInt locknr);
115 
116  // The destructor flushes (i.e. writes) the table if it is opened
117  // for output and not marked for delete.
118  virtual ~PlainTable();
119 
120  // Return the layout of a table (i.e. description and #rows).
121  // This function has the advantage that only the minimal amount of
122  // information required is read from the table, thus it is much
123  // faster than a normal table open.
124  // <br> The number of rows is returned. The description of the table
125  // is stored in desc (its contents will be overwritten).
126  static void getLayout (TableDesc& desc, AipsIO& ios);
127 
128  // Try to reopen the table for read/write access.
129  // An exception is thrown if the table is not writable.
130  // Nothing is done if the table is already open for read/write.
131  virtual void reopenRW();
132 
133  // Is the table stored in big or little endian format?
134  virtual Bool asBigEndian() const;
135 
136  // Get the storage option used for the table.
137  virtual const StorageOption& storageOption() const;
138 
139  // Is the table in use (i.e. open) in another process?
140  // If <src>checkSubTables</src> is set, it is also checked if
141  // a subtable is used in another process.
142  virtual Bool isMultiUsed (Bool checkSubTables) const;
143 
144  // Get the locking info.
145  virtual const TableLock& lockOptions() const;
146 
147  // Merge the given lock info with the existing one.
148  virtual void mergeLock (const TableLock& lockOptions);
149 
150  // Has this process the read or write lock, thus can the table
151  // be read or written safely?
153 
154  // Try to lock the table for read or write access.
155  virtual Bool lock (FileLocker::LockType, uInt nattempts);
156 
157  // Unlock the table. This will also synchronize the table data,
158  // thus force the data to be written to disk.
159  virtual void unlock();
160 
161  // Do a release of an AutoLock when the inspection interval has expired.
162  // <src>always=True</src> means that the inspection is always done,
163  // thus not every 25th call or so.
164  void autoReleaseLock (Bool always = False);
165 
166  // Flush the table, i.e. write it to disk.
167  // Nothing will be done if the table is not writable.
168  // A flush can be executed at any time.
169  // When a table is marked for delete, the destructor will remove
170  // files written by intermediate flushes.
171  // Note that if necessary the destructor will do an implicit flush,
172  // unless it is executed due to an exception.
173  virtual void flush (Bool fsync, Bool recursive);
174 
175  // Resync the Table object with the table file.
176  virtual void resync();
177 
178  // Get the modify counter.
179  virtual uInt getModifyCounter() const;
180 
181  // Set the table to being changed.
182  virtual void setTableChanged();
183 
184  // Convert a Table option to an AipsIO file option.
185  // This is used by storage managers.
187 
188  // Test if the table is opened as writable.
189  virtual Bool isWritable() const;
190 
191  // Get the actual table description.
192  virtual TableDesc actualTableDesc() const;
193 
194  // Get the data manager info.
195  virtual Record dataManagerInfo() const;
196 
197  // Get readonly access to the table keyword set.
199 
200  // Get read/write access to the table keyword set.
201  // This requires that the table is locked (or it gets locked
202  // when using AutoLocking mode).
204 
205  // Get a column object using its index.
206  virtual BaseColumn* getColumn (uInt columnIndex) const;
207 
208  // Get a column object using its name.
209  virtual BaseColumn* getColumn (const String& columnName) const;
210 
211  // Test if it is possible to add a row to this table.
212  virtual Bool canAddRow() const;
213 
214  // Add one or more rows and possibly initialize them.
215  // This will fail for tables not supporting addition of rows.
216  virtual void addRow (uInt nrrow, Bool initialize);
217 
218  // Test if it is possible to remove a row from this table.
219  virtual Bool canRemoveRow() const;
220 
221  // Remove the given row.
222  // This will fail for tables not supporting removal of rows.
223  virtual void removeRow (uInt rownr);
224 
225  // Add a column to the table.
226  // The last Bool argument is not used in PlainTable, but can be used in
227  // other classes derived from BaseTable.
228  // <group>
229  virtual void addColumn (const ColumnDesc& columnDesc, Bool);
230  virtual void addColumn (const ColumnDesc& columnDesc,
231  const String& dataManager, Bool byName, Bool);
232  virtual void addColumn (const ColumnDesc& columnDesc,
233  const DataManager& dataManager, Bool);
234  virtual void addColumn (const TableDesc& tableDesc,
235  const DataManager& dataManager, Bool);
236  // </group>
237 
238  // Test if columns can be removed.
239  virtual Bool canRemoveColumn (const Vector<String>& columnNames) const;
240 
241  // Remove columns.
242  virtual void removeColumn (const Vector<String>& columnNames);
243 
244  // Test if a column can be renamed (yes).
245  virtual Bool canRenameColumn (const String& columnName) const;
246 
247  // Rename a column.
248  virtual void renameColumn (const String& newName, const String& oldName);
249 
250  // Rename a hypercolumn.
251  virtual void renameHypercolumn (const String& newName,
252  const String& oldName);
253 
254  // Find the data manager with the given name or for the given column.
255  virtual DataManager* findDataManager (const String& name,
256  Bool byColumn) const;
257 
258 
259  // Get access to the TableCache.
261  { return theirTableCache; }
262 
263 private:
264  // Copy constructor is forbidden, because copying a table requires
265  // some more knowledge (like table name of result).
266  // Declaring it private, makes it unusable.
268 
269  // Assignment is forbidden, because copying a table requires
270  // some more knowledge (like table name of result).
271  // Declaring it private, makes it unusable.
273 
274  // Close the object which is called by the destructor.
275  void closeObject();
276 
277  // Rename the subtables (used by rename function).
278  virtual void renameSubTables (const String& newName,
279  const String& oldName);
280 
281  // The callback function when a lock is released.
282  // This flushes the table data, writes the synchronization data
283  // into the MemoryIO object, and returns a pointer to it.
284  // <group>
285  static MemoryIO* releaseCallBack (void* plainTableObject, Bool always);
287  // </group>
288 
289  // When needed, write the table control information in an AipsIO file.
290  // Tell the storage managers to flush and close their files.
291  // It returns a switch to tell if the table control information has
292  // been written.
293  Bool putFile (Bool always);
294 
295  // Synchronize the table after having acquired a lock which says
296  // that main table data has changed.
297  // It check if the columns did not change.
298  // It updates the table and column keywords.
299  void syncTable();
300 
301  // Determine and set the endian format (big or little).
302  void setEndian (int endianFormat);
303 
304  // Throw an exception if the table is not writable.
305  void checkWritable (const char* func) const;
306 
307 
308  ColumnSet* colSetPtr_p; //# pointer to set of columns
309  Bool tableChanged_p; //# Has the main data changed?
310  Bool addToCache_p; //# Is table added to cache?
311  TableLockData* lockPtr_p; //# pointer to lock object
312  TableSyncData lockSync_p; //# table synchronization
313  Bool bigEndian_p; //# True = big endian canonical
314  //# False = little endian canonical
316  //# cache of open (plain) tables
318 };
319 
320 
321 
322 } //# NAMESPACE CASACORE - END
323 
324 #endif
casacore::TableDesc
Definition: TableDesc.h:188
casacore::PlainTable::lockSync_p
TableSyncData lockSync_p
Definition: PlainTable.h:312
casacore::PlainTable::reopenRW
virtual void reopenRW()
Try to reopen the table for read/write access.
casacore::PlainTable::doReleaseCallBack
MemoryIO * doReleaseCallBack(Bool always)
casacore::AipsIO
Definition: AipsIO.h:169
casacore::DataManager
Abstract base class for a data manager.
Definition: DataManager.h:225
casacore::PlainTable::closeObject
void closeObject()
Close the object which is called by the destructor.
casacore::PlainTable::canRemoveColumn
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed.
casacore::ByteIO::OpenOption
OpenOption
Define the possible ByteIO open options.
Definition: ByteIO.h:65
casacore::PlainTable::tableChanged_p
Bool tableChanged_p
Definition: PlainTable.h:309
casacore::PlainTable::keywordSet
virtual TableRecord & keywordSet()
Get readonly access to the table keyword set.
casacore::PlainTable::renameHypercolumn
virtual void renameHypercolumn(const String &newName, const String &oldName)
Rename a hypercolumn.
casacore::PlainTable::operator=
PlainTable & operator=(const PlainTable &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
casacore::PlainTable::toAipsIOFoption
static ByteIO::OpenOption toAipsIOFoption(int tableOption)
Convert a Table option to an AipsIO file option.
casacore::PlainTable::getColumn
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
casacore::TableSyncData
Definition: TableSyncData.h:79
casacore::PlainTable::lock
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Try to lock the table for read or write access.
casacore::PlainTable::lockOptions
virtual const TableLock & lockOptions() const
Get the locking info.
casacore::PlainTable::addToCache_p
Bool addToCache_p
Definition: PlainTable.h:310
casacore::TableCache
Definition: TableCache.h:95
casacore::TableRecord
Definition: TableRecord.h:183
casacore::PlainTable::addColumn
virtual void addColumn(const ColumnDesc &columnDesc, const DataManager &dataManager, Bool)
casacore::PlainTable
Definition: PlainTable.h:86
casacore::PlainTable::PlainTableCommon
void PlainTableCommon(SetupNewTable &, uInt nrrow, Bool initialize, const TableLock &lockOptions, int endianFormat, const TSMOption &tsmOption)
Common part of the constructor shared by MPI and non-MPI.
casacore::FileLocker::LockType
LockType
Define the possible lock types.
Definition: FileLocker.h:95
casacore::PlainTable::isWritable
virtual Bool isWritable() const
Test if the table is opened as writable.
casacore::MemoryIO
Definition: MemoryIO.h:125
casacore::PlainTable::PlainTable
PlainTable(const PlainTable &)
Copy constructor is forbidden, because copying a table requires some more knowledge (like table name ...
casacore::PlainTable::addColumn
virtual void addColumn(const ColumnDesc &columnDesc, Bool)
Add a column to the table.
casacore::BaseTable
Definition: BaseTable.h:104
casacore::PlainTable::colSetPtr_p
ColumnSet * colSetPtr_p
Definition: PlainTable.h:308
casacore::PlainTable::rwKeywordSet
virtual TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
casacore::PlainTable::setTableChanged
virtual void setTableChanged()
Set the table to being changed.
casacore::PlainTable::releaseCallBack
static MemoryIO * releaseCallBack(void *plainTableObject, Bool always)
The callback function when a lock is released.
casacore::PlainTable::theirTableCache
static TableCache theirTableCache
Definition: PlainTable.h:317
casacore::ColumnSet
Definition: ColumnSet.h:94
casacore::PlainTable::tsmOption_p
TSMOption tsmOption_p
Definition: PlainTable.h:315
casacore::PlainTable::addColumn
virtual void addColumn(const ColumnDesc &columnDesc, const String &dataManager, Bool byName, Bool)
casacore::PlainTable::removeColumn
virtual void removeColumn(const Vector< String > &columnNames)
Remove columns.
casacore::PlainTable::addRow
virtual void addRow(uInt nrrow, Bool initialize)
Add one or more rows and possibly initialize them.
casacore::BaseTable::tableDesc
const TableDesc & tableDesc() const
Get the table description.
Definition: BaseTable.h:272
casacore::PlainTable::getLayout
static void getLayout(TableDesc &desc, AipsIO &ios)
Return the layout of a table (i.e.
casacore::BaseColumn
Definition: BaseColumn.h:99
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::PlainTable::tableCache
static TableCache & tableCache()
Get access to the TableCache.
Definition: PlainTable.h:260
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::PlainTable::renameSubTables
virtual void renameSubTables(const String &newName, const String &oldName)
Rename the subtables (used by rename function).
casacore::PlainTable::renameColumn
virtual void renameColumn(const String &newName, const String &oldName)
Rename a column.
casacore::PlainTable::bigEndian_p
Bool bigEndian_p
Definition: PlainTable.h:313
casacore::PlainTable::resync
virtual void resync()
Resync the Table object with the table file.
casacore::SetupNewTable
Create a new table - define shapes, data managers, etc.
Definition: SetupNewTab.h:347
casacore::PlainTable::isMultiUsed
virtual Bool isMultiUsed(Bool checkSubTables) const
Is the table in use (i.e.
casacore::PlainTable::putFile
Bool putFile(Bool always)
When needed, write the table control information in an AipsIO file.
casacore::PlainTable::hasLock
virtual Bool hasLock(FileLocker::LockType) const
Has this process the read or write lock, thus can the table be read or written safely?
casacore::PlainTable::canAddRow
virtual Bool canAddRow() const
Test if it is possible to add a row to this table.
casacore::TableLock
Definition: TableLock.h:69
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::PlainTable::dataManagerInfo
virtual Record dataManagerInfo() const
Get the data manager info.
casacore::PlainTable::setEndian
void setEndian(int endianFormat)
Determine and set the endian format (big or little).
casacore::PlainTable::storageOption
virtual const StorageOption & storageOption() const
Get the storage option used for the table.
casacore::PlainTable::unlock
virtual void unlock()
Unlock the table.
casacore::PlainTable::checkWritable
void checkWritable(const char *func) const
Throw an exception if the table is not writable.
casacore::PlainTable::asBigEndian
virtual Bool asBigEndian() const
Is the table stored in big or little endian format?
casacore::PlainTable::flush
virtual void flush(Bool fsync, Bool recursive)
Flush the table, i.e.
casacore::TSMOption
Definition: TSMOption.h:117
casacore::PlainTable::syncTable
void syncTable()
Synchronize the table after having acquired a lock which says that main table data has changed.
casacore::PlainTable::PlainTable
PlainTable(SetupNewTable &, uInt nrrow, Bool initialize, const TableLock &lockOptions, int endianFormat, const TSMOption &tsmOption)
Construct the object for a new table.
casacore::BaseTable::tableOption
int tableOption() const
Get the table option.
Definition: BaseTable.h:253
casacore::PlainTable::removeRow
virtual void removeRow(uInt rownr)
Remove the given row.
casacore::PlainTable::PlainTable
PlainTable(AipsIO &, uInt version, const String &name, const String &type, uInt nrrow, int option, const TableLock &lockOptions, const TSMOption &tsmOption, Bool addToCache, uInt locknr)
Construct the object for an existing table.
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::PlainTable::mergeLock
virtual void mergeLock(const TableLock &lockOptions)
Merge the given lock info with the existing one.
casacore::Record
Definition: Record.h:181
casacore::PlainTable::lockPtr_p
TableLockData * lockPtr_p
Definition: PlainTable.h:311
casacore::Vector
Definition: Vector.h:89
casacore::PlainTable::canRemoveRow
virtual Bool canRemoveRow() const
Test if it is possible to remove a row from this table.
casacore::PlainTable::findDataManager
virtual DataManager * findDataManager(const String &name, Bool byColumn) const
Find the data manager with the given name or for the given column.
casacore::PlainTable::autoReleaseLock
void autoReleaseLock(Bool always=False)
Do a release of an AutoLock when the inspection interval has expired.
casacore::PlainTable::~PlainTable
virtual ~PlainTable()
The destructor flushes (i.e.
casacore::PlainTable::getColumn
virtual BaseColumn * getColumn(const String &columnName) const
Get a column object using its name.
casacore::StorageOption
Definition: StorageOption.h:77
casacore::PlainTable::actualTableDesc
virtual TableDesc actualTableDesc() const
Get the actual table description.
casacore::PlainTable::PlainTable
PlainTable(MPI_Comm mpiComm, SetupNewTable &, uInt nrrow, Bool initialize, const TableLock &lockOptions, int endianFormat, const TSMOption &tsmOption)
MPI version of the constructor.
casacore::TableLockData
Definition: TableLockData.h:64
casacore::PlainTable::addColumn
virtual void addColumn(const TableDesc &tableDesc, const DataManager &dataManager, Bool)
casacore::ColumnDesc
Definition: ColumnDesc.h:132
casacore::PlainTable::canRenameColumn
virtual Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed (yes).
casacore::PlainTable::getModifyCounter
virtual uInt getModifyCounter() const
Get the modify counter.