PlainTable.h

Go to the documentation of this file.
00001 //# PlainTable.h: Class defining a plain regular table
00002 //# Copyright (C) 1994,1995,1996,1997,1998,1999,2000,2001,2002,2003
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef TABLES_PLAINTABLE_H
00029 #define TABLES_PLAINTABLE_H
00030 
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/tables/Tables/BaseTable.h>
00035 #include <casacore/tables/Tables/TableCache.h>
00036 #include <casacore/tables/Tables/TableRecord.h>
00037 #include <casacore/tables/Tables/TableSyncData.h>
00038 #include <casacore/tables/DataMan/TSMOption.h>
00039 #include <casacore/casa/IO/AipsIO.h>
00040 
00041 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00042 
00043 //# Forward Declarations
00044 class SetupNewTable;
00045 class TableLock;
00046 class TableLockData;
00047 class ColumnSet;
00048 class IPosition;
00049 class AipsIO;
00050 class MemoryIO;
00051 
00052 
00053 // <summary>
00054 // Class defining a plain regular table
00055 // </summary>
00056 
00057 // <use visibility=local>
00058 
00059 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
00060 // </reviewed>
00061 
00062 // <prerequisite>
00063 //# Classes you should understand before using this one.
00064 //   <li> BaseTable
00065 //   <li> BaseColumn
00066 // </prerequisite>
00067 
00068 // <etymology>
00069 // PlainTable represents a plain regular table. This is opposed to a
00070 // RefTable, which is a view on a PlainTable.
00071 // </etymology>
00072 
00073 // <synopsis> 
00074 // PlainTable is a table consisting of a keyword set and a number of
00075 // filled and virtual columns. The table control information and the
00076 // keyword set is stored in an AipsIO file. The data in the filled columns
00077 // are stored separately by storage managers.
00078 // </synopsis> 
00079 
00080 // <todo asof="$DATE:$">
00081 //# A List of bugs, limitations, extensions or planned refinements.
00082 //   <li> notify RefTable's when deleting rows
00083 // </todo>
00084 
00085 class PlainTable : public BaseTable
00086 {
00087 public:
00088 
00089     // Construct the object for a new table.
00090     // It creates storage manager(s) for unbound columns and initializes
00091     // all storage managers. The given number of rows is stored in
00092     // the table and initialized if the flag is set.
00093     PlainTable (SetupNewTable&, uInt nrrow, Bool initialize,
00094                 const TableLock& lockOptions, int endianFormat,
00095                 const TSMOption& tsmOption);
00096 
00097     // Construct the object for an existing table.
00098     // It opens the table file, reads the table control information
00099     // and creates and initializes the required storage managers.
00100     PlainTable (AipsIO&, uInt version, const String& name, const String& type,
00101                 uInt nrrow, int option, const TableLock& lockOptions,
00102                 const TSMOption& tsmOption, Bool addToCache, uInt locknr);
00103 
00104     // The destructor flushes (i.e. writes) the table if it is opened
00105     // for output and not marked for delete.
00106     virtual ~PlainTable();
00107 
00108     // Return the layout of a table (i.e. description and #rows).
00109     // This function has the advantage that only the minimal amount of
00110     // information required is read from the table, thus it is much
00111     // faster than a normal table open.
00112     // <br> The number of rows is returned. The description of the table
00113     // is stored in desc (its contents will be overwritten).
00114     static void getLayout (TableDesc& desc, AipsIO& ios);
00115 
00116     // Try to reopen the table for read/write access.
00117     // An exception is thrown if the table is not writable.
00118     // Nothing is done if the table is already open for read/write.
00119     virtual void reopenRW();
00120 
00121     // Is the table stored in big or little endian format?
00122     virtual Bool asBigEndian() const;
00123 
00124     // Get the storage option used for the table.
00125     virtual const StorageOption& storageOption() const;
00126 
00127     // Is the table in use (i.e. open) in another process?
00128     // If <src>checkSubTables</src> is set, it is also checked if
00129     // a subtable is used in another process.
00130     virtual Bool isMultiUsed (Bool checkSubTables) const;
00131 
00132     // Get the locking info.
00133     virtual const TableLock& lockOptions() const;
00134 
00135     // Merge the given lock info with the existing one.
00136     virtual void mergeLock (const TableLock& lockOptions);
00137 
00138     // Has this process the read or write lock, thus can the table
00139     // be read or written safely?
00140     virtual Bool hasLock (FileLocker::LockType) const;
00141 
00142     // Try to lock the table for read or write access.
00143     virtual Bool lock (FileLocker::LockType, uInt nattempts);
00144 
00145     // Unlock the table. This will also synchronize the table data,
00146     // thus force the data to be written to disk.
00147     virtual void unlock();
00148 
00149     // Do a release of an AutoLock when the inspection interval has expired.
00150     // <src>always=True</src> means that the inspection is always done,
00151     // thus not every 25th call or so.
00152     void autoReleaseLock (Bool always = False);
00153 
00154     // Flush the table, i.e. write it to disk.
00155     // Nothing will be done if the table is not writable.
00156     // A flush can be executed at any time.
00157     // When a table is marked for delete, the destructor will remove
00158     // files written by intermediate flushes.
00159     // Note that if necessary the destructor will do an implicit flush,
00160     // unless it is executed due to an exception.
00161     virtual void flush (Bool fsync, Bool recursive);
00162 
00163     // Resync the Table object with the table file.
00164     virtual void resync();
00165 
00166     // Get the modify counter.
00167     virtual uInt getModifyCounter() const;
00168 
00169     // Set the table to being changed.
00170     virtual void setTableChanged();
00171 
00172     // Convert a Table option to an AipsIO file option.
00173     // This is used by storage managers.
00174     static ByteIO::OpenOption toAipsIOFoption (int tableOption);
00175 
00176     // Test if the table is opened as writable.
00177     virtual Bool isWritable() const;
00178 
00179     // Get the actual table description.
00180     virtual TableDesc actualTableDesc() const;
00181 
00182     // Get the data manager info.
00183     virtual Record dataManagerInfo() const;
00184 
00185     // Get readonly access to the table keyword set.
00186     virtual TableRecord& keywordSet();
00187 
00188     // Get read/write access to the table keyword set.
00189     // This requires that the table is locked (or it gets locked
00190     // when using AutoLocking mode).
00191     virtual TableRecord& rwKeywordSet();
00192 
00193     // Get a column object using its index.
00194     virtual BaseColumn* getColumn (uInt columnIndex) const;
00195 
00196     // Get a column object using its name.
00197     virtual BaseColumn* getColumn (const String& columnName) const;
00198 
00199     // Test if it is possible to add a row to this table.
00200     virtual Bool canAddRow() const;
00201 
00202     // Add one or more rows and possibly initialize them.
00203     // This will fail for tables not supporting addition of rows.
00204     virtual void addRow (uInt nrrow, Bool initialize);
00205 
00206     // Test if it is possible to remove a row from this table.
00207     virtual Bool canRemoveRow() const;
00208 
00209     // Remove the given row.
00210     // This will fail for tables not supporting removal of rows.
00211     virtual void removeRow (uInt rownr);
00212 
00213     // Add a column to the table.
00214     // The last Bool argument is not used in PlainTable, but can be used in
00215     // other classes derived from BaseTable.
00216     // <group>
00217     virtual void addColumn (const ColumnDesc& columnDesc, Bool);
00218     virtual void addColumn (const ColumnDesc& columnDesc,
00219                             const String& dataManager, Bool byName, Bool);
00220     virtual void addColumn (const ColumnDesc& columnDesc,
00221                             const DataManager& dataManager, Bool);
00222     virtual void addColumn (const TableDesc& tableDesc,
00223                             const DataManager& dataManager, Bool);
00224     // </group>
00225 
00226     // Test if columns can be removed.
00227     virtual Bool canRemoveColumn (const Vector<String>& columnNames) const;
00228 
00229     // Remove columns.
00230     virtual void removeColumn (const Vector<String>& columnNames);
00231 
00232     // Test if a column can be renamed (yes).
00233     virtual Bool canRenameColumn (const String& columnName) const;
00234 
00235     // Rename a column.
00236     virtual void renameColumn (const String& newName, const String& oldName);
00237 
00238     // Rename a hypercolumn.
00239     virtual void renameHypercolumn (const String& newName,
00240                                     const String& oldName);
00241 
00242     // Find the data manager with the given name or for the given column.
00243     virtual DataManager* findDataManager (const String& name,
00244                                           Bool byColumn) const;
00245 
00246 
00247     // Get access to the TableCache.
00248     static TableCache& tableCache()
00249       { return theirTableCache; }
00250 
00251 private:
00252     // Copy constructor is forbidden, because copying a table requires
00253     // some more knowledge (like table name of result).
00254     // Declaring it private, makes it unusable.
00255     PlainTable (const PlainTable&);
00256 
00257     // Assignment is forbidden, because copying a table requires
00258     // some more knowledge (like table name of result).
00259     // Declaring it private, makes it unusable.
00260     PlainTable& operator= (const PlainTable&);
00261 
00262     // Close the object which is called by the destructor.
00263     void closeObject();
00264 
00265     // Rename the subtables (used by rename function).
00266     virtual void renameSubTables (const String& newName,
00267                                   const String& oldName);
00268 
00269     // The callback function when a lock is released.
00270     // This flushes the table data, writes the synchronization data
00271     // into the MemoryIO object, and returns a pointer to it.
00272     // <group>
00273     static MemoryIO* releaseCallBack (void* plainTableObject, Bool always);
00274     MemoryIO* doReleaseCallBack (Bool always);
00275     // </group>
00276 
00277     // When needed, write the table control information in an AipsIO file.
00278     // Tell the storage managers to flush and close their files.
00279     // It returns a switch to tell if the table control information has
00280     // been written.
00281     Bool putFile (Bool always);
00282 
00283     // Synchronize the table after having acquired a lock which says
00284     // that main table data has changed.
00285     // It check if the columns did not change.
00286     // It updates the table and column keywords.
00287     void syncTable();
00288 
00289     // Determine and set the endian format (big or little).
00290     void setEndian (int endianFormat);
00291 
00292     // Throw an exception if the table is not writable.
00293     void checkWritable (const char* func) const;
00294 
00295 
00296     ColumnSet*     colSetPtr_p;        //# pointer to set of columns
00297     Bool           tableChanged_p;     //# Has the main data changed?
00298     Bool           addToCache_p;       //# Is table added to cache?
00299     TableLockData* lockPtr_p;          //# pointer to lock object
00300     TableSyncData  lockSync_p;         //# table synchronization
00301     Bool           bigEndian_p;        //# True  = big endian canonical
00302                                        //# False = little endian canonical
00303     TSMOption      tsmOption_p;
00304     //# cache of open (plain) tables
00305     static TableCache theirTableCache;
00306 };
00307 
00308 
00309 
00310 } //# NAMESPACE CASACORE - END
00311 
00312 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1