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  // Construct the object for an existing table.
98  // It opens the table file, reads the table control information
99  // and creates and initializes the required storage managers.
100  PlainTable (AipsIO&, uInt version, const String& name, const String& type,
101  uInt nrrow, int option, const TableLock& lockOptions,
102  const TSMOption& tsmOption, Bool addToCache, uInt locknr);
103 
104  // The destructor flushes (i.e. writes) the table if it is opened
105  // for output and not marked for delete.
106  virtual ~PlainTable();
107 
108  // Return the layout of a table (i.e. description and #rows).
109  // This function has the advantage that only the minimal amount of
110  // information required is read from the table, thus it is much
111  // faster than a normal table open.
112  // <br> The number of rows is returned. The description of the table
113  // is stored in desc (its contents will be overwritten).
114  static void getLayout (TableDesc& desc, AipsIO& ios);
115 
116  // Try to reopen the table for read/write access.
117  // An exception is thrown if the table is not writable.
118  // Nothing is done if the table is already open for read/write.
119  virtual void reopenRW();
120 
121  // Is the table stored in big or little endian format?
122  virtual Bool asBigEndian() const;
123 
124  // Get the storage option used for the table.
125  virtual const StorageOption& storageOption() const;
126 
127  // Is the table in use (i.e. open) in another process?
128  // If <src>checkSubTables</src> is set, it is also checked if
129  // a subtable is used in another process.
130  virtual Bool isMultiUsed (Bool checkSubTables) const;
131 
132  // Get the locking info.
133  virtual const TableLock& lockOptions() const;
134 
135  // Merge the given lock info with the existing one.
136  virtual void mergeLock (const TableLock& lockOptions);
137 
138  // Has this process the read or write lock, thus can the table
139  // be read or written safely?
140  virtual Bool hasLock (FileLocker::LockType) const;
141 
142  // Try to lock the table for read or write access.
143  virtual Bool lock (FileLocker::LockType, uInt nattempts);
144 
145  // Unlock the table. This will also synchronize the table data,
146  // thus force the data to be written to disk.
147  virtual void unlock();
148 
149  // Do a release of an AutoLock when the inspection interval has expired.
150  // <src>always=True</src> means that the inspection is always done,
151  // thus not every 25th call or so.
152  void autoReleaseLock (Bool always = False);
153 
154  // Flush the table, i.e. write it to disk.
155  // Nothing will be done if the table is not writable.
156  // A flush can be executed at any time.
157  // When a table is marked for delete, the destructor will remove
158  // files written by intermediate flushes.
159  // Note that if necessary the destructor will do an implicit flush,
160  // unless it is executed due to an exception.
161  virtual void flush (Bool fsync, Bool recursive);
162 
163  // Resync the Table object with the table file.
164  virtual void resync();
165 
166  // Get the modify counter.
167  virtual uInt getModifyCounter() const;
168 
169  // Set the table to being changed.
170  virtual void setTableChanged();
171 
172  // Convert a Table option to an AipsIO file option.
173  // This is used by storage managers.
175 
176  // Test if the table is opened as writable.
177  virtual Bool isWritable() const;
178 
179  // Get the actual table description.
180  virtual TableDesc actualTableDesc() const;
181 
182  // Get the data manager info.
183  virtual Record dataManagerInfo() const;
184 
185  // Get readonly access to the table keyword set.
186  virtual TableRecord& keywordSet();
187 
188  // Get read/write access to the table keyword set.
189  // This requires that the table is locked (or it gets locked
190  // when using AutoLocking mode).
191  virtual TableRecord& rwKeywordSet();
192 
193  // Get a column object using its index.
194  virtual BaseColumn* getColumn (uInt columnIndex) const;
195 
196  // Get a column object using its name.
197  virtual BaseColumn* getColumn (const String& columnName) const;
198 
199  // Test if it is possible to add a row to this table.
200  virtual Bool canAddRow() const;
201 
202  // Add one or more rows and possibly initialize them.
203  // This will fail for tables not supporting addition of rows.
204  virtual void addRow (uInt nrrow, Bool initialize);
205 
206  // Test if it is possible to remove a row from this table.
207  virtual Bool canRemoveRow() const;
208 
209  // Remove the given row.
210  // This will fail for tables not supporting removal of rows.
211  virtual void removeRow (uInt rownr);
212 
213  // Add a column to the table.
214  // The last Bool argument is not used in PlainTable, but can be used in
215  // other classes derived from BaseTable.
216  // <group>
217  virtual void addColumn (const ColumnDesc& columnDesc, Bool);
218  virtual void addColumn (const ColumnDesc& columnDesc,
219  const String& dataManager, Bool byName, Bool);
220  virtual void addColumn (const ColumnDesc& columnDesc,
221  const DataManager& dataManager, Bool);
222  virtual void addColumn (const TableDesc& tableDesc,
223  const DataManager& dataManager, Bool);
224  // </group>
225 
226  // Test if columns can be removed.
227  virtual Bool canRemoveColumn (const Vector<String>& columnNames) const;
228 
229  // Remove columns.
230  virtual void removeColumn (const Vector<String>& columnNames);
231 
232  // Test if a column can be renamed (yes).
233  virtual Bool canRenameColumn (const String& columnName) const;
234 
235  // Rename a column.
236  virtual void renameColumn (const String& newName, const String& oldName);
237 
238  // Rename a hypercolumn.
239  virtual void renameHypercolumn (const String& newName,
240  const String& oldName);
241 
242  // Find the data manager with the given name or for the given column.
243  virtual DataManager* findDataManager (const String& name,
244  Bool byColumn) const;
245 
246 
247  // Get access to the TableCache.
249  { return theirTableCache; }
250 
251 private:
252  // Copy constructor is forbidden, because copying a table requires
253  // some more knowledge (like table name of result).
254  // Declaring it private, makes it unusable.
255  PlainTable (const PlainTable&);
256 
257  // Assignment is forbidden, because copying a table requires
258  // some more knowledge (like table name of result).
259  // Declaring it private, makes it unusable.
261 
262  // Close the object which is called by the destructor.
263  void closeObject();
264 
265  // Rename the subtables (used by rename function).
266  virtual void renameSubTables (const String& newName,
267  const String& oldName);
268 
269  // The callback function when a lock is released.
270  // This flushes the table data, writes the synchronization data
271  // into the MemoryIO object, and returns a pointer to it.
272  // <group>
273  static MemoryIO* releaseCallBack (void* plainTableObject, Bool always);
274  MemoryIO* doReleaseCallBack (Bool always);
275  // </group>
276 
277  // When needed, write the table control information in an AipsIO file.
278  // Tell the storage managers to flush and close their files.
279  // It returns a switch to tell if the table control information has
280  // been written.
281  Bool putFile (Bool always);
282 
283  // Synchronize the table after having acquired a lock which says
284  // that main table data has changed.
285  // It check if the columns did not change.
286  // It updates the table and column keywords.
287  void syncTable();
288 
289  // Determine and set the endian format (big or little).
290  void setEndian (int endianFormat);
291 
292  // Throw an exception if the table is not writable.
293  void checkWritable (const char* func) const;
294 
295 
296  ColumnSet* colSetPtr_p; //# pointer to set of columns
297  Bool tableChanged_p; //# Has the main data changed?
298  Bool addToCache_p; //# Is table added to cache?
299  TableLockData* lockPtr_p; //# pointer to lock object
300  TableSyncData lockSync_p; //# table synchronization
301  Bool bigEndian_p; //# True = big endian canonical
302  //# False = little endian canonical
304  //# cache of open (plain) tables
306 };
307 
308 
309 
310 } //# NAMESPACE CASACORE - END
311 
312 #endif
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
virtual void unlock()
Unlock the table.
Create a new table - define shapes, data managers, etc.
Definition: SetupNewTab.h:346
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
MemoryIO * doReleaseCallBack(Bool always)
Class defining a plain regular table.
Definition: PlainTable.h:85
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Try to lock the table for read or write access.
virtual void mergeLock(const TableLock &lockOptions)
Merge the given lock info with the existing one.
void checkWritable(const char *func) const
Throw an exception if the table is not writable.
TableLockData * lockPtr_p
Definition: PlainTable.h:299
TSMOption tsmOption_p
Definition: PlainTable.h:303
virtual void removeRow(uInt rownr)
Remove the given row.
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
virtual const StorageOption & storageOption() const
Get the storage option used for 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 Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed (yes).
Envelope class for the description of a table column.
Definition: ColumnDesc.h:131
Class to hold table synchronization data.
Definition: TableSyncData.h:78
virtual void renameSubTables(const String &newName, const String &oldName)
Rename the subtables (used by rename function).
Class to hold table lock data.
Definition: TableLockData.h:63
virtual void addColumn(const ColumnDesc &columnDesc, Bool)
Add a column to the table.
void setEndian(int endianFormat)
Determine and set the endian format (big or little).
static TableCache theirTableCache
Definition: PlainTable.h:305
Class to manage a set of table columns.
Definition: ColumnSet.h:93
virtual Bool isMultiUsed(Bool checkSubTables) const
Is the table in use (i.e.
virtual TableRecord & keywordSet()
Get readonly access to the table keyword set.
Options defining how table files are organized.
Definition: StorageOption.h:71
virtual const TableLock & lockOptions() const
Get the locking info.
Abstract base class for tables.
Definition: BaseTable.h:99
virtual void renameColumn(const String &newName, const String &oldName)
Rename a column.
virtual Bool asBigEndian() const
Is the table stored in big or little endian format?
virtual Bool isWritable() const
Test if the table is opened as writable.
virtual Bool canAddRow() const
Test if it is possible to add a row to this table.
Options for the Tiled Storage Manager Access.
Definition: TSMOption.h:116
Cache of open tables.
Definition: TableCache.h:94
virtual void flush(Bool fsync, Bool recursive)
Flush the table, i.e.
virtual TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
ColumnSet * colSetPtr_p
Definition: PlainTable.h:296
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
static void getLayout(TableDesc &desc, AipsIO &ios)
Return the layout of a table (i.e.
static TableCache & tableCache()
Get access to the TableCache.
Definition: PlainTable.h:248
virtual DataManager * findDataManager(const String &name, Bool byColumn) const
Find the data manager with the given name or for the given column.
PlainTable(SetupNewTable &, uInt nrrow, Bool initialize, const TableLock &lockOptions, int endianFormat, const TSMOption &tsmOption)
Construct the object for a new table.
const Bool False
Definition: aipstype.h:41
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 reopenRW()
Try to reopen the table for read/write access.
virtual Record dataManagerInfo() const
Get the data manager info.
void closeObject()
Close the object which is called by the destructor.
Bool putFile(Bool always)
When needed, write the table control information in an AipsIO file.
OpenOption
Define the possible ByteIO open options.
Definition: ByteIO.h:65
virtual void removeColumn(const Vector< String > &columnNames)
Remove columns.
virtual void addRow(uInt nrrow, Bool initialize)
Add one or more rows and possibly initialize them.
Abstract base class for a data manager.
Definition: DataManager.h:222
void syncTable()
Synchronize the table after having acquired a lock which says that main table data has changed...
TableSyncData lockSync_p
Definition: PlainTable.h:300
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Class for IO to a memory buffer.
Definition: MemoryIO.h:124
virtual ~PlainTable()
The destructor flushes (i.e.
virtual TableDesc actualTableDesc() const
Get the actual table description.
void autoReleaseLock(Bool always=False)
Do a release of an AutoLock when the inspection interval has expired.
Define the structure of a Casacore table.
Definition: TableDesc.h:186
PlainTable & operator=(const PlainTable &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
static ByteIO::OpenOption toAipsIOFoption(int tableOption)
Convert a Table option to an AipsIO file option.
virtual uInt getModifyCounter() const
Get the modify counter.
LockType
Define the possible lock types.
Definition: FileLocker.h:95
const TableDesc & tableDesc() const
Get the table description.
Definition: BaseTable.h:259
virtual void resync()
Resync the Table object with the table file.
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
static MemoryIO * releaseCallBack(void *plainTableObject, Bool always)
The callback function when a lock is released.
unsigned int uInt
Definition: aipstype.h:48
virtual void setTableChanged()
Set the table to being changed.
virtual void renameHypercolumn(const String &newName, const String &oldName)
Rename a hypercolumn.
Abstract base class for a table column.
Definition: BaseColumn.h:98