casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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?
152  virtual Bool hasLock (FileLocker::LockType) const;
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.
198  virtual TableRecord& keywordSet();
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).
203  virtual TableRecord& rwKeywordSet();
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.
267  PlainTable (const PlainTable&);
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);
286  MemoryIO* doReleaseCallBack (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
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
A 1-D Specialization of the Array class.
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:253
int MPI_Comm
Definition: MPIGlue.h:59
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:311
TSMOption tsmOption_p
Definition: PlainTable.h:315
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).
virtual casacore::String type() const
Implements RegionShape::type.
Definition: RegionShapes.h:548
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
static TableCache theirTableCache
Definition: PlainTable.h:317
Class to manage a set of table columns.
Definition: ColumnSet.h:93
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.
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:76
virtual const TableLock & lockOptions() const
Get the locking info.
Abstract base class for tables.
Definition: BaseTable.h:103
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:308
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
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:260
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:44
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:224
void syncTable()
Synchronize the table after having acquired a lock which says that main table data has changed...
TableSyncData lockSync_p
Definition: PlainTable.h:312
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:187
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:272
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.
static MemoryIO * releaseCallBack(void *plainTableObject, Bool always)
The callback function when a lock is released.
unsigned int uInt
Definition: aipstype.h:51
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
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42