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