DataManager.h

Go to the documentation of this file.
00001 //# DataManager.h: Abstract base classes for a data manager
00002 //# Copyright (C) 1994,1995,1996,1997,1998,1999,2001,2002
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_DATAMANAGER_H
00029 #define TABLES_DATAMANAGER_H
00030 
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/tables/Tables/ColumnCache.h>
00035 #include <casacore/tables/DataMan/TSMOption.h>
00036 #include <casacore/casa/BasicSL/String.h>
00037 #include <casacore/casa/BasicSL/Complex.h>
00038 #include <casacore/casa/Containers/SimOrdMap.h>
00039 #include <casacore/casa/IO/ByteIO.h>
00040 #include <casacore/casa/OS/Mutex.h>
00041 #include<iosfwd>
00042 
00043 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00044 
00045 //# Forward Declarations
00046 class DataManager;
00047 class DataManagerColumn;
00048 class SetupNewTable;
00049 class Table;
00050 class MultiFileBase;
00051 class Record;
00052 class IPosition;
00053 class Slicer;
00054 class RefRows;
00055 template<class T> class Array;
00056 class AipsIO;
00057 
00058 
00059 // <summary>
00060 // Define the type of the static construction function.
00061 // </summary>
00062 
00063 // <use visibility=local>
00064 
00065 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
00066 // </reviewed>
00067 
00068 // <synopsis>
00069 // Class names of data managers and pointers to their associated constructor
00070 // function are registered in a static map to be able to create the correct
00071 // data manager object from a string giving the type name of the data manager.
00072 // DataManagerCtor is the type of the constructor functions.
00073 // </synopsis>
00074 // <group name=DataManagerCtor>
00075 typedef DataManager* (*DataManagerCtor) (const String& dataManagerType,
00076                                          const Record& spec);
00077 // </group>
00078 
00079 
00080 // <summary>
00081 // Abstract base class for a data manager
00082 // </summary>
00083 
00084 // <use visibility=local>
00085 
00086 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
00087 // </reviewed>
00088 
00089 // <prerequisite>
00090 //# Classes you should understand before using this one.
00091 // </prerequisite>
00092 
00093 // <synopsis> 
00094 // DataManager is the abstract base class for all kind of table data managers.
00095 // There are currently 2 classes of data managers:
00096 // <ul>
00097 //  <li> Storage managers handling the storage of data. These classes
00098 //         have to be derived from DataManager.
00099 //         StManAipsIO is an example of a storage manager.
00100 //  <li> Virtual column engines handling the on-the-fly calculation
00101 //         of data, which are not stored as such. The base class for
00102 //         these is VirtualColumnEngine (which is derived from DataManager),
00103 //         from which all virtual columns engine must be derived from.
00104 // </ul>
00105 // DataManager contains some common data and defines several virtual
00106 // functions, which usually have to be implemented in the derived classes.
00107 // It also contains some helper functions for the derived classes
00108 // (like fileName().
00109 //
00110 // The actual handling of a column by the data manager is defined in
00111 // the abstract base class
00112 // <linkto class="DataManagerColumn:description">DataManagerColumn</linkto>.
00113 // Each data manager must
00114 // have an associated class (derived from DataManagerColumn) to
00115 // handle the columns.
00116 //
00117 // There is a protocol defined how a data manager is created and
00118 // initialized. For a new table it is:
00119 // <ul>
00120 //  <li>
00121 //   The user creates data managers and binds them to columns. For example:
00122 //   <srcblock>
00123 //   SetupNewTable newtab("name.data", Table::New);  // set up new table
00124 //   StManAipsIO stman;                       // define storage manager
00125 //   newtab.bindColumn ("column1", stman);    // bind column to st.man.
00126 //   newtab.bindColumn ("column2", stman);    // bind column to st.man.
00127 //   Table tab(newtab);                       // actually create table
00128 //   </srcblock>
00129 //   When the given data manager object is used for the first time in a bind
00130 //   function, a copy of the object is made using the clone function.
00131 //   Thus in the above example column1 and column2 share the same data
00132 //   manager; only at the first bind the stman object is cloned.
00133 //   Columns not explicitly bound to a data manager get implicitly bound
00134 //   to the default data manager (as defined in the column description)
00135 //   by the Table constructor (as used in line 5).
00136 //  <li>
00137 //   After binding the unbound columns, the PlainTable constructor sets up
00138 //   the data managers. For each column it asks the data manager to
00139 //   construct a DataManagerColumn object (in fact, an object of a class
00140 //   derived from DataManagerColumn). This is done by the functions
00141 //   createScalarColumn, createIndArrColumn and createDirArrColumn.
00142 //   For each data manager the create function is called. This allows
00143 //   them to initialize themselves and/or to call an initialization
00144 //   function in their column objects.
00145 //   This is, for instance, used by the storage managers to create files.
00146 //   Thereafter the prepare function is called to allow the data managers
00147 //   to do further initialization possibly requiring information from
00148 //   other columns.
00149 //  <li>
00150 //   When the table gets written (by the PlainTable destructor),
00151 //   the flush function is called for each data manager. This allows
00152 //   the data manager or their column objects to write or flush their data.
00153 //   The table system takes care of storing the information required
00154 //   to reconstruct the data managers. It uses the function dataManagerType
00155 //   to store the (unique) type name of the data manager class.
00156 //  <li>
00157 //   Finally each data manager object gets deleted. Their destructors
00158 //   must delete their column objects (if any and if needed).
00159 // </ul>
00160 // For an existing table the procedure is slightly different:
00161 // <ul>
00162 //  <li>
00163 //   The statement
00164 //   <br><src> Table tab("name.data"); </src>
00165 //   will create a table object for an existing table. This has the effect
00166 //   that the given table file will be read to reconstruct the Table object
00167 //   and the data managers.
00168 //  <li>
00169 //   The stored data manager class names are used to reconstruct
00170 //   the data managers. This uses the static registration map, which
00171 //   maps the class name to a static class constructor function (usually
00172 //   called makeObject). This requires that the type name and constructor
00173 //   for each possible data manager are registered before the table
00174 //   is opened. The DataManager function registerMainCtor (implemented
00175 //   in DataManager.cc) is called before a table is opened, so registration
00176 //   of data managers should, in principle, be done there.
00177 //   <br>However, for unknown data managers it is tried to load a shared
00178 //   library whose name is the lowercase version of the data manager without a
00179 //   possible template argument (e.g. <src>bitflagsengine</src> for
00180 //   data manager <src>BitFlagsEngine<Int></src>).
00181 //   It can be preceeded by lib or libcasa_ and followed by .so or .dylib.
00182 //   The shared library has to have a function with a name like
00183 //   <src>register_bitflagsengine</src> that must register the data manager(s).
00184 //   The function must be declared as <src>extern "C"</src>, otherwise its
00185 //   name gets mangled.
00186 //  <li>
00187 //   Each table column is bound to the correct data manager. The sequence
00188 //   number stored in the table file is used for that purpose.
00189 //  <li>
00190 //   The DataManager createXXXColumn functions are called for each table
00191 //   column to let the data manager construct a data manager column object.
00192 //  <li>
00193 //   For each data manager the open function is called to allow it and
00194 //   its column objects to read back the information stored in the
00195 //   flush function.
00196 //   Thereafter the prepare function is called for each data manager
00197 //   to allow it to initialize some variables.
00198 //   The reason that open and prepare are separated is that in order to
00199 //   initialize variables it may be required to use other columns.
00200 //   So it may be needed that all columns are read back before they
00201 //   get initialized.
00202 //  <li>
00203 //   Similar to a new table the flush functions gets called when the
00204 //   table gets written. Destruction is also the same as sketched
00205 //   for new tables.
00206 // </ul>
00207 // </synopsis> 
00208 
00209 // <motivation>
00210 // An abstract base class is needed to support data managers and
00211 // virtual column engines in the table system in a transparant way.
00212 // </motivation>
00213 
00214 // <todo asof="$DATE:$">
00215 //# A List of bugs, limitations, extensions or planned refinements.
00216 //  <li> Handle unregistered data managers in a better way.
00217 //         Instead of throwing an exception a subprocess could be
00218 //         started which represents the data manager.
00219 // </todo>
00220 
00221 
00222 class DataManager
00223 {
00224 friend class SetupNewTable;
00225 friend class ColumnSet;
00226 
00227 public:
00228 
00229     // Default constructor.
00230     DataManager();
00231 
00232     virtual ~DataManager();
00233 
00234     // Make a clone of the derived object.
00235     virtual DataManager* clone() const = 0;
00236 
00237     // Return the name of the data manager. This is the name of this
00238     // instantiation of the data manager, thus not its type name.
00239     // By default it returns an empty string.
00240     virtual String dataManagerName() const;
00241 
00242     // Return the type name of the data manager (in fact its class name).
00243     // It has to be a unique name, thus if the class is templated
00244     // the template parameter has to be part of the name.
00245     // This is used by the open/flush mechanism to be able to reconstruct
00246     // the correct data manager.
00247     virtual String dataManagerType() const = 0;
00248 
00249     // Add SEQNR and SPEC (the DataManagerSpec subrecord) to the info.
00250     void dataManagerInfo (Record& info) const;
00251 
00252     // Return a record containing data manager specifications.
00253     // The default implementation returns an empty record.
00254     virtual Record dataManagerSpec() const;
00255 
00256     // Get data manager properties that can be modified.
00257     // It is a subset of the data manager specification.
00258     // The default implementation returns an empty record.
00259     virtual Record getProperties() const;
00260 
00261     // Modify data manager properties given in record fields. Only the
00262     // properties as returned by getProperties are used, others are ignored.
00263     // The default implementation does nothing.
00264     virtual void setProperties (const Record& spec);
00265 
00266     // Is the data manager a storage manager?
00267     // The default is yes.
00268     virtual Bool isStorageManager() const;
00269 
00270     // Tell if the data manager wants to reallocate the data manager
00271     // column objects.
00272     // This is used by the tiling storage manager.
00273     // By default it returns False.
00274     virtual Bool canReallocateColumns() const;
00275 
00276     // Reallocate the column object if it is part of this data manager.
00277     // It returns a pointer to the new column object.
00278     // This function is used by the tiling storage manager.
00279     // By default it does nothing and returns the input pointer.
00280     virtual DataManagerColumn* reallocateColumn (DataManagerColumn* column);
00281     
00282     // Get the (unique) sequence nr of this data manager.
00283     uInt sequenceNr() const
00284         { return seqnr_p; }
00285 
00286     // Get the nr of columns in this data manager (can be zero).
00287     uInt ncolumn() const
00288         { return nrcol_p; }
00289 
00290     // Have the data to be stored in big or little endian canonical format?
00291     Bool asBigEndian() const
00292       { return asBigEndian_p; }
00293 
00294     // Get the TSM option.
00295     const TSMOption& tsmOption() const
00296       { return tsmOption_p; }
00297 
00298     // Get the MultiFile pointer (can be 0).
00299     MultiFileBase* multiFile()
00300       { return multiFile_p; }
00301 
00302     // Compose a keyword name from the given keyword appended with the
00303     // sequence number (e.g. key_0).
00304     // This makes the keyword name unique if multiple data managers
00305     // are used with the same type.
00306     String keywordName (const String& keyword) const;
00307 
00308     // Compose a unique filename from the table name and sequence number.
00309     String fileName() const;
00310 
00311     // Get the AipsIO option of the underlying file.
00312     ByteIO::OpenOption fileOption() const;
00313 
00314     // Is this a regular storage manager?
00315     // It is regular if it allows addition of rows and writing data in them.
00316     // <br>The default implementation returns True.
00317     virtual Bool isRegular() const;
00318 
00319     // Get the table this object is associated with.
00320     Table& table() const
00321         { return *table_p; }
00322 
00323     // Reopen the data manager for read/write access.
00324     // By default it is assumed that a reopen for read/write does
00325     // not have to do anything.
00326     virtual void reopenRW();
00327 
00328     // Does the data manager allow to add rows? (default no)
00329     virtual Bool canAddRow() const;
00330 
00331     // Does the data manager allow to delete rows? (default no)
00332     virtual Bool canRemoveRow() const;
00333 
00334     // Does the data manager allow to add columns? (default no)
00335     virtual Bool canAddColumn() const;
00336 
00337     // Does the data manager allow to delete columns? (default no)
00338     virtual Bool canRemoveColumn() const;
00339 
00340     // Does the data manager allow to rename columns? (default yes)
00341     virtual Bool canRenameColumn() const;
00342 
00343     // Set the maximum cache size (in bytes) to be used by a storage manager.
00344     // The default implementation does nothing.
00345     virtual void setMaximumCacheSize (uInt nbytes);
00346 
00347     // Show the data manager's IO statistics. By default it does nothing.
00348     virtual void showCacheStatistics (std::ostream&) const;
00349 
00350     // Create a column in the data manager on behalf of a table column.
00351     // It calls makeXColumn and checks the data type.
00352     // <group>
00353     // Create a scalar column.
00354     // The <src>dataTypeId</src> argument is gives the id (i.e. name)
00355     // of the data type of the column. It is only used for virtual
00356     // columns of a non-standard data type to be able to check if
00357     // the correctness of the column data type.
00358     // <br>Storage managers only handle standard data types and
00359     // can readily ignore this argument.
00360     DataManagerColumn* createScalarColumn (const String& columnName,
00361                                            int dataType,
00362                                            const String& dataTypeId);
00363     // Create a direct array column.
00364     DataManagerColumn* createDirArrColumn (const String& columnName,
00365                                            int dataType,
00366                                            const String& dataTypeId);
00367     // Create an indirect array column.
00368     DataManagerColumn* createIndArrColumn (const String& columnName,
00369                                            int dataType,
00370                                            const String& dataTypeId);
00371     // </group>
00372 
00373     // The data manager will be deleted (because all its columns are
00374     // requested to be deleted).
00375     // So clean up the things needed (e.g. delete files).
00376     virtual void deleteManager() = 0;
00377 
00378 
00379 protected:
00380     // Decrement number of columns (in case a column is deleted).
00381     void decrementNcolumn()
00382         { nrcol_p--; }
00383 
00384     // Tell the data manager if big or little endian format is needed.
00385     void setEndian (Bool bigEndian)
00386       { asBigEndian_p = bigEndian; }
00387 
00388     // Tell the data manager which TSM option to use.
00389     void setTsmOption (const TSMOption& tsmOption);
00390 
00391     // Tell the data manager that MultiFile can be used.
00392     // Because MultiFile cannot be used with mmapped files, it sets
00393     // the TSMOption accordingly.
00394     void setMultiFile (MultiFileBase* mfile);
00395 
00396     // Does the data manager support use of MultiFile?
00397     // A derived class has to return True if it can use the MultiFile.
00398     // The default implementation returns False.
00399     virtual Bool hasMultiFileSupport() const;
00400 
00401     // Throw an exception in case data type is TpOther, because the
00402     // storage managers (and maybe other data managers) do not support
00403     // such columns.
00404     void throwDataTypeOther (const String& columnName, int dataType) const;
00405 
00406 
00407 private:
00408     uInt         nrcol_p;            //# #columns in this st.man.
00409     uInt         seqnr_p;            //# Unique nr of this st.man. in a Table
00410     Bool         asBigEndian_p;      //# store data in big or little endian
00411     TSMOption    tsmOption_p;
00412     MultiFileBase* multiFile_p;      //# MultiFile to use; 0=no MultiFile
00413     Table*       table_p;            //# Table this data manager belongs to
00414     mutable DataManager* clone_p;    //# Pointer to clone (used by SetupNewTab)
00415 
00416 
00417     // The copy constructor cannot be used for this base class.
00418     // The clone function should be used instead.
00419     // The private declaration of this constructor makes it unusable.
00420     DataManager (const DataManager&);
00421 
00422     // Assignment cannot be used for this base class.
00423     // The private declaration of this operator makes it unusable.
00424     DataManager& operator= (const DataManager&);
00425 
00426     // Create a column in the data manager on behalf of a table column.
00427     //# Should be private, but has to be public because friend
00428     //# declaration gave internal CFront error.
00429     // <group>
00430     // Create a scalar column.
00431     virtual DataManagerColumn* makeScalarColumn (const String& columnName,
00432                                                  int dataType,
00433                                                  const String& dataTypeId) = 0;
00434     // Create a direct array column.
00435     virtual DataManagerColumn* makeDirArrColumn (const String& columnName,
00436                                                  int dataType,
00437                                                  const String& dataTypeId) = 0;
00438     // Create an indirect array column.
00439     virtual DataManagerColumn* makeIndArrColumn (const String& columnName,
00440                                                  int dataType,
00441                                                  const String& dataTypeId) = 0;
00442     // </group>
00443 
00444     // Check if the data type of the created data manager column is correct.
00445     void checkDataType (const DataManagerColumn* colPtr,
00446                         const String& columnName,
00447                         int dataType, const String& dataTypeId) const;
00448 
00449     // Add rows to all columns.
00450     // The default implementation throws a "not possible" exception.
00451     virtual void addRow (uInt nrrow);
00452 
00453     // Delete a row from all columns.
00454     // The default implementation throws a "not possible" exception.
00455     virtual void removeRow (uInt rownr);
00456 
00457     // Add a column.
00458     // The default implementation throws a "not possible" exception.
00459     virtual void addColumn (DataManagerColumn*);
00460 
00461     // Delete a column.
00462     // The default implementation throws a "not possible" exception.
00463     virtual void removeColumn (DataManagerColumn*);
00464 
00465     // Set the sequence number of this data manager.
00466     void setSeqnr (uInt nr)
00467         { seqnr_p = nr; }
00468 
00469     // Link the data manager to the Table object.
00470     void linkToTable (Table& tab);
00471 
00472     // Flush and optionally fsync the data.
00473     // The AipsIO stream represents the main table file and can be
00474     // used by virtual column engines to store SMALL amounts of data.
00475     // It returns a True status if it had to flush (i.e. if data have changed).
00476     virtual Bool flush (AipsIO& ios, Bool fsync) = 0;
00477 
00478     // Let the data manager initialize itself for a new table.
00479     virtual void create (uInt nrrow) = 0;
00480 
00481     // Let the data manager initialize itself for an existing table.
00482     // The AipsIO stream represents the main table file and must be
00483     // used by virtual column engines to retrieve the data stored
00484     // in the flush function.
00485     virtual void open (uInt nrrow, AipsIO& ios) = 0;
00486 
00487     // Open as above.
00488     // The data manager can return the number of rows it thinks there are.
00489     // This is particularly useful for data managers like LofarStMan whose
00490     // data are written outside the table system, thus for which no rows
00491     // have been added.
00492     // <br>By default it calls open and returns <src>nrrow</src>.
00493     virtual uInt open1 (uInt nrrow, AipsIO& ios);
00494 
00495     // Resync the data by rereading cached data from the file.
00496     // This is called when a lock is acquired on the file and it appears 
00497     // that data in this data manager has been changed by another process.
00498     virtual void resync (uInt nrrow) = 0;
00499 
00500     // Resync as above.
00501     // The data manager can return the number of rows it thinks there are.
00502     // This is particularly useful for data managers like LofarStMan whose
00503     // data are written outside the table system, thus for which no rows
00504     // have been added.
00505     // <br>By default it calls resync and returns <src>nrrow</src>.
00506     virtual uInt resync1 (uInt nrrow);
00507 
00508     // Let the data manager initialize itself further.
00509     // Prepare is called after create/open has been called for all
00510     // columns. In this way one can be sure that referenced columns
00511     // are read back and partly initialized.
00512     // The default implementation does nothing.
00513     virtual void prepare();
00514 
00515     // Declare the mapping of the data manager type name to a static
00516     // "makeObject" function.
00517     static SimpleOrderedMap<String,DataManagerCtor> theirRegisterMap;
00518     static MutexedInit theirMutexedInit;
00519 
00520 public:
00521     // Has the object already been cloned?
00522     DataManager* getClone() const
00523         { return clone_p; }
00524 
00525     // Set the pointer to the clone.
00526     void setClone (DataManager* clone) const
00527         { clone_p = clone; }
00528 
00529     // Register a mapping of a data manager type to its static construction
00530     // function. It is fully thread-safe.
00531     static void registerCtor (const String& type, DataManagerCtor func);
00532 
00533     // Get the "constructor" of a data manager (thread-safe).
00534     static DataManagerCtor getCtor (const String& dataManagerType);
00535 
00536     // Test if a data manager is registered (thread-safe).
00537     static Bool isRegistered (const String& dataManagerType);
00538 
00539     // Register the main data managers (if not done yet).
00540     // It is fully thread-safe.
00541     static void registerMainCtor()
00542       { theirMutexedInit.exec(); }
00543 
00544     // Serve as default function for theirRegisterMap, which catches all
00545     // unknown data manager types.
00546     // <thrown>
00547     //   <li> TableUnknownDataManager
00548     // </thrown>
00549     static DataManager* unknownDataManager (const String& dataManagerType,
00550                                             const Record& spec);
00551 
00552 private:
00553     // Register a data manager constructor.
00554     static void unlockedRegisterCtor (const String& type,
00555                                       DataManagerCtor func)
00556       { theirRegisterMap.define (type, func); }
00557 
00558     // Do the actual (thread-safe) registration of the main data managers.
00559     static void doRegisterMainCtor (void*);
00560 };
00561 
00562 
00563 
00564 
00565 // <summary>
00566 // Abstract base class for a column in a data manager
00567 // </summary>
00568 
00569 // <use visibility=local>
00570 
00571 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
00572 // </reviewed>
00573 
00574 // <prerequisite>
00575 //# Classes you should understand before using this one.
00576 //   <li> DataManager
00577 // </prerequisite>
00578 
00579 // <etymology>
00580 // DataManagerColumn handles a column for a data manager.
00581 // </etymology>
00582 
00583 // <synopsis> 
00584 // DataManagerColumn is the abstract base class to handle a column in
00585 // a data manager. Each data manager class must have one or more associated
00586 // classes derived from DataManagerColumn to handle the columns.
00587 // For example, storage manager StManAipsIO has columns classes
00588 // StManColumnAipsIO, StManColumnArrayAipsIO and StManColumnIndArrayAipsIO
00589 // to handle scalars, direct arrays and indirect arrays, resp..
00590 // However, using multiple inheritance it is possible that the derived
00591 // DataManager and DataManagerColumn classes are the same. This is used
00592 // in class ScaledArrayEngine<S,T> which represents both the data manager
00593 // and its column class. It can do that, because the virtual column engine
00594 // <linkto class="ScaledArrayEngine:description">ScaledArrayEngine</linkto>
00595 // can handle only one column.
00596 //
00597 // In the synopsis of class DataManager it is described how the (derived)
00598 // DataManagerColumn objects gets created and deleted.
00599 // 
00600 // DataManagerColumn defines various virtual functions to get or put (slices)
00601 // of data in a column. These functions are called by the table column
00602 // classes ScalarColumnData and ArrayColumnData.
00603 // It does not define functions create, open, flush and prepare like
00604 // those defined in DataManager. It is left to the derived classes to
00605 // define those as needed and to interact properly with their
00606 // data manager object.
00607 // </synopsis> 
00608 
00609 // <motivation>
00610 // An abstract base class is needed to support multiple data
00611 // managers in the table system
00612 // </motivation>
00613 
00614 // <todo asof="$DATE:$">
00615 //# A List of bugs, limitations, extensions or planned refinements.
00616 // </todo>
00617 
00618 
00619 class DataManagerColumn
00620 {
00621 public:
00622 
00623     // Create a column.
00624     DataManagerColumn()
00625         : isFixedShape_p(False) {;}
00626 
00627     // Frees up the storage.
00628     virtual ~DataManagerColumn();
00629 
00630     // Set the isFixedShape flag.
00631     void setIsFixedShape (Bool isFixedShape)
00632         { isFixedShape_p = isFixedShape; }
00633 
00634     // Is this a fixed shape column?
00635     Bool isFixedShape() const
00636         { return isFixedShape_p; }
00637 
00638     // Get the data type of the column as defined in DataType.h.
00639     virtual int dataType() const = 0;
00640 
00641     // Get the data type id of the column for dataType==TpOther.
00642     // The default implementation returns an emptry string.
00643     // This function is required for virtual column engines handling
00644     // non-standard data types. It is used to check the data type.
00645     virtual String dataTypeId() const;
00646 
00647     // Test if data can be put into this column.
00648     // This does not test if the data file is writable, only if
00649     // it is in principle allowed to store data into the column.
00650     // (It may not be allowed for virtual columns).
00651     // The default is True.
00652     virtual Bool isWritable() const;
00653 
00654     // Set the maximum length of the value (can be used for strings).
00655     // By default the maximum length is ignored.
00656     virtual void setMaxLength (uInt maxLength);
00657 
00658     // Set the shape of all (fixed-shaped) arrays in the column.
00659     // Effectively it is the same as setShapeColumn, but it also sets
00660     // the isFixedShape_p flag.
00661     void setFixedShapeColumn (const IPosition& shape)
00662         { setShapeColumn (shape); isFixedShape_p = True; }
00663 
00664     // Set the shape of an (variable-shaped) array in the given row.
00665     // By default it throws a "not possible" exception.
00666     virtual void setShape (uInt rownr, const IPosition& shape);
00667 
00668     // Set the shape and tile shape of an (variable-shaped) array
00669     // in the given row.
00670     // By default it ignores the tile shape (thus only sets the shape).
00671     virtual void setShapeTiled (uInt rownr, const IPosition& shape,
00672                                 const IPosition& tileShape);
00673 
00674     // Is the value shape defined in the given row?
00675     // By default it returns True.
00676     virtual Bool isShapeDefined (uInt rownr);
00677 
00678     // Get the dimensionality of the item in the given row.
00679     // By default it returns shape(rownr).nelements().
00680     virtual uInt ndim (uInt rownr);
00681 
00682     // Get the shape of the item in the given row.
00683     // By default it returns a zero-length IPosition (for a scalar value).
00684     virtual IPosition shape (uInt rownr);
00685 
00686     // Get the tile shape of the item in the given row.
00687     // By default it returns a zero-length IPosition.
00688     virtual IPosition tileShape (uInt rownr);
00689 
00690     // Can the data manager handle chaging the shape of an existing array?
00691     // Default is no.
00692     virtual Bool canChangeShape() const;
00693 
00694     // Can the column data manager handle access to a scalar column?
00695     // If not, the caller should access the column by looping through
00696     // all cells in the column.
00697     // Default is no.
00698     // <br>
00699     // The returned reask switch determines if the information is
00700     // permanent. False indicates it is permanent; True indicates it
00701     // will be reasked for the next get/putColumn.
00702     // By default reask is set to False.
00703     virtual Bool canAccessScalarColumn (Bool& reask) const;
00704 
00705     // Can the column data manager handle access to a clooection of cells
00706     // in a scalar column?
00707     // If not, the caller should access the column cells by looping through
00708     // the cells in the column.
00709     // Default is no.
00710     // <br>
00711     // The returned reask switch determines if the information is
00712     // permanent. False indicates it is permanent; True indicates it
00713     // will be reasked for the next get/putColumn.
00714     // By default reask is set to False.
00715     virtual Bool canAccessScalarColumnCells (Bool& reask) const;
00716 
00717     // Can the column data manager handle access to a scalar column?
00718     // If not, the caller should access the column by looping through
00719     // all cells in the column.
00720     // Default is no.
00721     // <br>
00722     // The returned reask switch determines if the information is
00723     // permanent. False indicates it is permanent; True indicates it
00724     // will be reasked for the next get/putColumn.
00725     // By default reask is set to False.
00726     virtual Bool canAccessArrayColumn (Bool& reask) const;
00727 
00728     // Can the column data manager handle access to a collection of cells
00729     // in an array column?
00730     // If not, the caller should access the column cells by looping through
00731     // the cells in the column.
00732     // Default is no.
00733     // <br>
00734     // The returned reask switch determines if the information is
00735     // permanent. False indicates it is permanent; True indicates it
00736     // will be reasked for the next get/putColumn.
00737     // By default reask is set to False.
00738     virtual Bool canAccessArrayColumnCells (Bool& reask) const;
00739 
00740     // Can the column data manager handle access to a cell slice?
00741     // If not, the caller should do slicing itself (by accessing the
00742     // entire array and slicing it).
00743     // Default is no.
00744     // <br>
00745     // The returned reask switch determines if the information is
00746     // permanent. False indicates it is permanent; True indicates it
00747     // will be reasked for the next get/putColumn.
00748     // By default reask is set to False.
00749     virtual Bool canAccessSlice (Bool& reask) const;
00750 
00751     // Can the column data manager handle access to a column slice?
00752     // If not, the caller should access the column slice by looping through
00753     // all cell slices in the column.
00754     // Default is no.
00755     // <br>
00756     // The returned reask switch determines if the information is
00757     // permanent. False indicates it is permanent; True indicates it
00758     // will be reasked for the next get/putColumn.
00759     // By default reask is set to False.
00760     virtual Bool canAccessColumnSlice (Bool& reask) const;
00761 
00762     // Get access to the ColumnCache object.
00763     // <group>
00764     ColumnCache& columnCache()
00765         { return colCache_p; }
00766     const ColumnCache* columnCachePtr() const
00767         { return &colCache_p; }
00768     // </group>
00769 
00770     // Get the scalar value in the given row.
00771     // These functions are non-virtual and are converted to their
00772     // virtual getV equivalent to achieve that a derived templated class
00773     //(like VirtualScalarColumn) does not have to declare and implement
00774     // all these functions.
00775     // The compiler complains about hiding virtual functions if you do not
00776     // declare all virtual functions with the same name in a derived class.
00777     // <group>
00778     void get (uInt rownr, Bool* dataPtr)
00779         { getBoolV (rownr, dataPtr); }
00780     void get (uInt rownr, uChar* dataPtr)
00781         { getuCharV (rownr, dataPtr); }
00782     void get (uInt rownr, Short* dataPtr)
00783         { getShortV (rownr, dataPtr); }
00784     void get (uInt rownr, uShort* dataPtr)
00785         { getuShortV (rownr, dataPtr); }
00786     void get (uInt rownr, Int* dataPtr)
00787         { getIntV (rownr, dataPtr); }
00788     void get (uInt rownr, uInt* dataPtr)
00789         { getuIntV (rownr, dataPtr); }
00790     void get (uInt rownr, float* dataPtr)
00791         { getfloatV (rownr, dataPtr); } 
00792    void get (uInt rownr, double* dataPtr)
00793         { getdoubleV (rownr, dataPtr); }
00794     void get (uInt rownr, Complex* dataPtr)
00795         { getComplexV (rownr, dataPtr); }
00796     void get (uInt rownr, DComplex* dataPtr)
00797         { getDComplexV (rownr, dataPtr); }
00798     void get (uInt rownr, String* dataPtr)
00799         { getStringV (rownr, dataPtr); }
00800     // This function is the get for all non-standard data types.
00801     void get (uInt rownr, void* dataPtr)
00802         { getOtherV (rownr, dataPtr); }
00803     // </group>
00804 
00805     // Put the scalar value into the given row.
00806     // These functions are non-virtual and are converted to their
00807     // virtual putV equivalent to achieve that a derived templated class
00808     //(like VirtualScalarColumn) does not have to declare and implement
00809     // all these functions.
00810     // The compiler complains about hiding virtual functions if you do not
00811     // declare all virtual functions with the same name in a derived class.
00812     // <group>
00813     void put (uInt rownr, const Bool* dataPtr)
00814         { putBoolV (rownr, dataPtr); }
00815     void put (uInt rownr, const uChar* dataPtr)
00816         { putuCharV (rownr, dataPtr); }
00817     void put (uInt rownr, const Short* dataPtr)
00818         { putShortV (rownr, dataPtr); }
00819     void put (uInt rownr, const uShort* dataPtr)
00820         { putuShortV (rownr, dataPtr); }
00821     void put (uInt rownr, const Int* dataPtr)
00822         { putIntV (rownr, dataPtr); }
00823     void put (uInt rownr, const uInt* dataPtr)
00824         { putuIntV (rownr, dataPtr); }
00825     void put (uInt rownr, const float* dataPtr)
00826         { putfloatV (rownr, dataPtr); }
00827     void put (uInt rownr, const double* dataPtr)
00828         { putdoubleV (rownr, dataPtr); }
00829     void put (uInt rownr, const Complex* dataPtr)
00830         { putComplexV (rownr, dataPtr); }
00831     void put (uInt rownr, const DComplex* dataPtr)
00832         { putDComplexV (rownr, dataPtr); }
00833     void put (uInt rownr, const String* dataPtr)
00834         { putStringV (rownr, dataPtr); }
00835     // This function is the put for all non-standard data types.
00836     void put (uInt rownr, const void* dataPtr)
00837         { putOtherV (rownr, dataPtr); }
00838     // </group>
00839 
00840     // Get all scalar values in the column.
00841     // The argument dataPtr is in fact a Vector<T>*, but a void*
00842     // is needed to be generic.
00843     // The vector pointed to by dataPtr has to have the correct length
00844     // (which is guaranteed by the ScalarColumn getColumn function).
00845     // The default implementation throws an "invalid operation" exception.
00846     virtual void getScalarColumnV (void* dataPtr);
00847 
00848     // Put all scalar values in the column.
00849     // The argument dataPtr is in fact a const Vector<T>*, but a const void*
00850     // is needed to be generic.
00851     // The vector pointed to by dataPtr has to have the correct length
00852     // (which is guaranteed by the ScalarColumn putColumn function).
00853     // The default implementation throws an "invalid operation" exception.
00854     virtual void putScalarColumnV (const void* dataPtr);
00855 
00856     // Get some scalar values in the column.
00857     // The argument dataPtr is in fact a Vector<T>*, but a void*
00858     // is needed to be generic.
00859     // The vector pointed to by dataPtr has to have the correct length
00860     // (which is guaranteed by the ScalarColumn getColumn function).
00861     // The default implementation throws an "invalid operation" exception.
00862     virtual void getScalarColumnCellsV (const RefRows& rownrs,
00863                                         void* dataPtr);
00864 
00865     // Put some scalar values in the column.
00866     // The argument dataPtr is in fact a const Vector<T>*, but a const void*
00867     // is needed to be generic.
00868     // The vector pointed to by dataPtr has to have the correct length
00869     // (which is guaranteed by the ScalarColumn getColumn function).
00870     // The default implementation throws an "invalid operation" exception.
00871     virtual void putScalarColumnCellsV (const RefRows& rownrs,
00872                                         const void* dataPtr);
00873 
00874     // Get scalars from the given row on with a maximum of nrmax values.
00875     // It returns the actual number of values got.
00876     // This can be used to get an entire column of scalars or to get
00877     // a part of a column (for a cache for example).
00878     // The argument dataPtr is in fact a T*, but a void*
00879     // is needed to be generic.
00880     // The default implementation throws an "invalid operation" exception.
00881     virtual uInt getBlockV (uInt rownr, uInt nrmax, void* dataPtr);
00882 
00883     // Put nrmax scalars from the given row on.
00884     // It returns the actual number of values put.
00885     // This can be used to put an entire column of scalars or to put
00886     // a part of a column (for a cache for example).
00887     // The argument dataPtr is in fact a const T*, but a const void*
00888     // is needed to be generic.
00889     // The default implementation throws an "invalid operation" exception.
00890     virtual void putBlockV (uInt rownr, uInt nrmax, const void* dataPtr);
00891 
00892     // Get the array value in the given row.
00893     // The argument dataPtr is in fact an Array<T>*, but a void*
00894     // is needed to be generic.
00895     // The array pointed to by dataPtr has to have the correct shape
00896     // (which is guaranteed by the ArrayColumn get function).
00897     // The default implementation throws an "invalid operation" exception.
00898     virtual void getArrayV (uInt rownr, void* dataPtr);
00899 
00900     // Put the array value into the given row.
00901     // The argument dataPtr is in fact a const Array<T>*, but a const void*
00902     // is needed to be generic.
00903     // The array pointed to by dataPtr has to have the correct shape
00904     // (which is guaranteed by the ArrayColumn put function).
00905     // The default implementation throws an "invalid operation" exception.
00906     virtual void putArrayV (uInt rownr, const void* dataPtr);
00907 
00908     // Get all array values in the column.
00909     // The argument dataPtr is in fact an Array<T>*, but a void*
00910     // is needed to be generic.
00911     // The vector pointed to by dataPtr has to have the correct length
00912     // (which is guaranteed by the ArrayColumn getColumn function).
00913     // The default implementation throws an "invalid operation" exception.
00914     virtual void getArrayColumnV (void* dataPtr);
00915 
00916     // Put all array values in the column.
00917     // The argument dataPtr is in fact a const Array<T>*, but a const void*
00918     // is needed to be generic.
00919     // The vector pointed to by dataPtr has to have the correct length
00920     // (which is guaranteed by the ArrayColumn putColumn function).
00921     // The default implementation throws an "invalid operation" exception.
00922     virtual void putArrayColumnV (const void* dataPtr);
00923 
00924     // Get some array values in the column.
00925     // The argument dataPtr is in fact an Array<T>*, but a void*
00926     // is needed to be generic.
00927     // The vector pointed to by dataPtr has to have the correct length
00928     // (which is guaranteed by the ArrayColumn getColumn function).
00929     // The default implementation throws an "invalid operation" exception.
00930     virtual void getArrayColumnCellsV (const RefRows& rownrs,
00931                                        void* dataPtr);
00932 
00933     // Put some array values in the column.
00934     // The argument dataPtr is in fact an const Array<T>*, but a const void*
00935     // is needed to be generic.
00936     // The vector pointed to by dataPtr has to have the correct length
00937     // (which is guaranteed by the ArrayColumn getColumn function).
00938     // The default implementation throws an "invalid operation" exception.
00939     virtual void putArrayColumnCellsV (const RefRows& rownrs,
00940                                        const void* dataPtr);
00941 
00942     // Get a section of the array in the given row.
00943     // The argument dataPtr is in fact an Array<T>*, but a void*
00944     // is needed to be generic.
00945     // The array pointed to by dataPtr has to have the correct shape
00946     // (which is guaranteed by the ArrayColumn getSlice function).
00947     // The default implementation throws an "invalid operation" exception.
00948     virtual void getSliceV (uInt rownr, const Slicer& slicer, void* dataPtr);
00949 
00950     // Put into a section of the array in the given row.
00951     // The argument dataPtr is in fact a const Array<T>*, but a const void*
00952     // is needed to be generic.
00953     // The array pointed to by dataPtr has to have the correct shape
00954     // (which is guaranteed by the ArrayColumn putSlice function).
00955     // The default implementation throws an "invalid operation" exception.
00956     virtual void putSliceV (uInt rownr, const Slicer& slicer,
00957                             const void* dataPtr);
00958 
00959     // Get a section of all arrays in the column.
00960     // The argument dataPtr is in fact an Array<T>*, but a void*
00961     // is needed to be generic.
00962     // The array pointed to by dataPtr has to have the correct shape
00963     // (which is guaranteed by the ArrayColumn getColumn function).
00964     // The default implementation throws an "invalid operation" exception.
00965     virtual void getColumnSliceV (const Slicer& slicer, void* dataPtr);
00966 
00967     // Put into a section of all arrays in the column.
00968     // The argument dataPtr is in fact a const Array<T>*, but a const void*
00969     // is needed to be generic.
00970     // The array pointed to by dataPtr has to have the correct shape
00971     // (which is guaranteed by the ArrayColumn putColumn function).
00972     // The default implementation throws an "invalid operation" exception.
00973     virtual void putColumnSliceV (const Slicer& slicer, const void* dataPtr);
00974 
00975     // Get a section of some arrays in the column.
00976     // The argument dataPtr is in fact an Array<T>*, but a void*
00977     // is needed to be generic.
00978     // The array pointed to by dataPtr has to have the correct shape
00979     // (which is guaranteed by the ArrayColumn getColumn function).
00980     // The default implementation throws an "invalid operation" exception.
00981     virtual void getColumnSliceCellsV (const RefRows& rownrs,
00982                                        const Slicer& slicer, void* dataPtr);
00983 
00984     // Put into a section of some arrays in the column.
00985     // The argument dataPtr is in fact a const Array<T>*, but a const void*
00986     // is needed to be generic.
00987     // The array pointed to by dataPtr has to have the correct shape
00988     // (which is guaranteed by the ArrayColumn putColumn function).
00989     // The default implementation throws an "invalid operation" exception.
00990     virtual void putColumnSliceCellsV (const RefRows& rownrs,
00991                                        const Slicer& slicer,
00992                                        const void* dataPtr);
00993 
00994     // Throw an "invalid operation" exception for the default
00995     // implementation of get.
00996     void throwGet() const;
00997 
00998     // Throw an "invalid operation" exception for the default
00999     // implementation of put.
01000     void throwPut() const;
01001 
01002     // Set the column name.
01003     void setColumnName (const String& colName)
01004       { colName_p = colName; }
01005 
01006     // Get rhe column name.
01007     const String& columnName() const
01008       { return colName_p; }
01009 
01010 protected:
01011     // Get the scalar value in the given row.
01012     // The default implementation throws an "invalid operation" exception.
01013     // <group>
01014     virtual void getBoolV     (uInt rownr, Bool* dataPtr);
01015     virtual void getuCharV    (uInt rownr, uChar* dataPtr);
01016     virtual void getShortV    (uInt rownr, Short* dataPtr);
01017     virtual void getuShortV   (uInt rownr, uShort* dataPtr);
01018     virtual void getIntV      (uInt rownr, Int* dataPtr);
01019     virtual void getuIntV     (uInt rownr, uInt* dataPtr);
01020     virtual void getfloatV    (uInt rownr, float* dataPtr);
01021     virtual void getdoubleV   (uInt rownr, double* dataPtr);
01022     virtual void getComplexV  (uInt rownr, Complex* dataPtr);
01023     virtual void getDComplexV (uInt rownr, DComplex* dataPtr);
01024     virtual void getStringV   (uInt rownr, String* dataPtr);
01025     // This function is the get for all non-standard data types.
01026     virtual void getOtherV    (uInt rownr, void* dataPtr);
01027     // </group>
01028 
01029     // Put the scalar value into the given row.
01030     // The default implementation throws an "invalid operation" exception.
01031     // <group>
01032     virtual void putBoolV     (uInt rownr, const Bool* dataPtr);
01033     virtual void putuCharV    (uInt rownr, const uChar* dataPtr);
01034     virtual void putShortV    (uInt rownr, const Short* dataPtr);
01035     virtual void putuShortV   (uInt rownr, const uShort* dataPtr);
01036     virtual void putIntV      (uInt rownr, const Int* dataPtr);
01037     virtual void putuIntV     (uInt rownr, const uInt* dataPtr);
01038     virtual void putfloatV    (uInt rownr, const float* dataPtr);
01039     virtual void putdoubleV   (uInt rownr, const double* dataPtr);
01040     virtual void putComplexV  (uInt rownr, const Complex* dataPtr);
01041     virtual void putDComplexV (uInt rownr, const DComplex* dataPtr);
01042     virtual void putStringV   (uInt rownr, const String* dataPtr);
01043     // This function is the put for all non-standard data types.
01044     virtual void putOtherV    (uInt rownr, const void* dataPtr);
01045     // </group>
01046 
01047 private:
01048     Bool        isFixedShape_p;
01049     String      colName_p;
01050     ColumnCache colCache_p;
01051 
01052     // Set the shape of all (fixed-shaped) arrays in the column.
01053     // By default it throws a "not possible" exception.
01054     virtual void setShapeColumn (const IPosition& shape);
01055 
01056     // The copy constructor cannot be used for this base class.
01057     // The private declaration of this constructor makes it unusable.
01058     DataManagerColumn (const DataManagerColumn&);
01059 
01060     // Assignment cannot be used for this base class.
01061     // The private declaration of this operator makes it unusable.
01062     DataManagerColumn& operator= (const DataManagerColumn&);
01063 };
01064 
01065 
01066 
01067 } //# NAMESPACE CASACORE - END
01068 
01069 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1