00001 //# BaseMappedArrayEngine.h: Abstract virtual column engine for virtual->stored mapping 00002 //# Copyright (C) 1995,1996,1997,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_BASEMAPPEDARRAYENGINE_H 00029 #define TABLES_BASEMAPPEDARRAYENGINE_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/tables/DataMan/VirtColEng.h> 00034 #include <casacore/tables/DataMan/VirtArrCol.h> 00035 #include <casacore/casa/Arrays/IPosition.h> 00036 00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00038 00039 //# Forward Declarations 00040 template<class T> class ArrayColumn; 00041 class TableColumn; 00042 00043 00044 // <summary> 00045 // Templated virtual column engine for a table array of any type. 00046 // </summary> 00047 00048 // <use visibility=export> 00049 00050 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests=""> 00051 // </reviewed> 00052 00053 // <prerequisite> 00054 //# Classes you should understand before using this one. 00055 // <li> <linkto class=VirtualColumnEngine>VirtualColumnEngine</linkto> 00056 // <li> <linkto class=VirtualArrayColumn>VirtualArrayColumn</linkto> 00057 // </prerequisite> 00058 00059 // <etymology> 00060 // BaseMappedArrayEngine contains for the 1-1 mapping of a virtual 00061 // column to a stored column (both containing arrays). 00062 // </etymology> 00063 00064 // <synopsis> 00065 // BaseMappedArrayEngine is an abstract base class for virtual column engines 00066 // which map data from the arrays in the virtual column to 00067 // the arrays in the stored column. Note the the stored column does not need 00068 // to be stored; it can be another virtual column, but usually it will be a 00069 // stored column. 00070 // Examples of classes using this base class are 00071 // <linkto class=ScaledArrayEngine>ScaledArrayEngine</linkto> and 00072 // <linkto class=RetypedArrayEngine>RetypedArrayEngine</linkto>. 00073 // 00074 // The virtual column has to be bound to the virtual column engine used 00075 // for it. The stored column will usually be bound to a storage manager, 00076 // but any other suitable data manager is possible. E.g. it is 00077 // possible to use <src>MappedArrayEngine<StokesVector,float></src> 00078 // to map a StokesVector to a float column, which in its turn uses 00079 // <src>ScaledArrayEngine<float,Int></src> to store it as integers. 00080 // Note that the names of the virtual and stored column have to be different, 00081 // otherwise the table system cannot distinguish them. 00082 // 00083 // This base class does several tasks for the derived classes. 00084 // The main one is to keep and handle the information about the virtual 00085 // and stored column. The name of the stored column is written as a keyword 00086 // in the virtual column. In this way the stored column is known when 00087 // a table is read back. It also creates <src>(RO)ArrayColumn<T></src> 00088 // objects to access the stored column. The function roColumn gives 00089 // read access, while rwColumn gives write access. 00090 // 00091 // An engine object should be used for one column only, because the stored 00092 // column name is part of the engine. If it would be used for more than 00093 // one column, they would all share the same stored column. 00094 // When the engine is bound to a column, it is checked if the name 00095 // of that column matches the given virtual column name. 00096 // 00097 // The engine can be used for a column containing any kind of array 00098 // (thus direct or indirect, fixed or variable shaped)) as long as the 00099 // virtual array can be stored in the stored array. Thus a fixed shaped 00100 // virtual can use a variable shaped stored, but not vice versa. 00101 // A fixed shape indirect virtual can use a stored with direct arrays. 00102 // 00103 // The DataManager framework contains various virtual functions. 00104 // This class implements several, but not all of them. Furthermore 00105 // some implementations may not be optimal or correct for derived classes. 00106 // Hereafter follows a list of functions which may need implementation 00107 // in derived classes. The classes mentioned in the examples below show 00108 // implementations of these functions. 00109 // <ul> 00110 // <li> 00111 // The following (virtual) functions have to be implemented: 00112 // <dl> 00113 // <dt><src> 00114 // ~... (the destructor) 00115 // </src> 00116 // <dt><src> 00117 // DataManager* clone() const; 00118 // </src> 00119 // <dt><src> 00120 // String dataManagerType() const; 00121 // </src> 00122 // <dt><src> 00123 // static void registerClass(); 00124 // </src> 00125 // <dt><src> 00126 // static DataManager* makeObject (const String& dataManagerType); 00127 // </src> 00128 // <dt><src> 00129 // void getArray (uInt rownr, Array<T>& data); 00130 // </src> 00131 // <dt><src> 00132 // void putArray (uInt rownr, const Array<T>& data); 00133 // </src> 00134 // (only if the virtual column is writable). 00135 // </dl> 00136 // <li> 00137 // For efficiency reasons it could be better to implement the following 00138 // functions: 00139 // <dl> 00140 // <dt><src> 00141 // void getSlice (uInt rownr, const Slicer& slicer, Array<T>& data); 00142 // </src> 00143 // <dt><src> 00144 // void putSlice (uInt rownr, const Slicer& slicer, 00145 // const Array<T>& data); 00146 // </src> 00147 // <dt><src> 00148 // void getArrayColumn (Array<T>& data); 00149 // </src> 00150 // <dt><src> 00151 // void putArrayColumn (const Array<T>& data); 00152 // </src> 00153 // <dt><src> 00154 // void getColumnSlice (const Slicer& slicer, Array<T>& data); 00155 // </src> 00156 // <dt><src> 00157 // void putColumnSlice (const Slicer& slicer, const Array<T>& data); 00158 // </src> 00159 // </dl> 00160 // <li> 00161 // The following functions have to be implemented when the shapes 00162 // of the virtual and stored arrays are not the same. 00163 // <dl> 00164 // <dt><src> 00165 // void setShapeColumn (const IPosition& shape); 00166 // </src> 00167 // <dt><src> 00168 // void setShape (uInt rownr, const IPosition& shape); 00169 // </src> 00170 // <dt><src> 00171 // uInt ndim (uInt rownr); 00172 // </src> 00173 // <dt><src> 00174 // IPosition shape (uInt rownr); 00175 // </src> 00176 // </dl> 00177 // <li> 00178 // The following functions deal with the initialization and persistence 00179 // of engine specific variables. When the class has variables of its 00180 // own, these functions may need to be implemented. Implementations of 00181 // create and prepare have to call the similar functions in this base class. 00182 // <dl> 00183 // <dt><src> 00184 // void close (AipsIO& ios); 00185 // </src> 00186 // <dt><src> 00187 // void create (uInt nrrow); 00188 // </src> 00189 // <dt><src> 00190 // void open (uInt nrrow, AipsIO& ios); 00191 // </src> 00192 // <dt><src> 00193 // void prepare(); 00194 // </src> 00195 // </dl> 00196 // <li> 00197 // The following functions do not need to be declared and implemented 00198 // in derived classes unless it is a very special case. 00199 // <dl> 00200 // <dt><src> 00201 // String dataManagerName() const; 00202 // </src> 00203 // <dt><src> 00204 // Bool canAddRow() const; 00205 // </src> 00206 // <dt><src> 00207 // Bool canRemoveRow() const; 00208 // </src> 00209 // <dt><src> 00210 // void addRow (uInt nrrow); 00211 // </src> 00212 // <dt><src> 00213 // void removeRow (uInt rownr); 00214 // </src> 00215 // <dt><src> 00216 // DataManagerColumn* makeDirArrColumn (const String& columnName, 00217 // int dataType, 00218 // const String& dataTypeId); 00219 // </src> 00220 // <dt><src> 00221 // DataManagerColumn* makeIndArrColumn (const String& columnName, 00222 // int dataType, 00223 // const String& dataTypeId); 00224 // </src> 00225 // <dt><src> 00226 // Bool isWritable() const; 00227 // </src> 00228 // <dt><src> 00229 // Bool isShapeDefined (uInt rownr); 00230 // </src> 00231 // </dl> 00232 // </ul> 00233 // </synopsis> 00234 00235 // <example> 00236 // The derived classes 00237 // <linkto class=ScaledArrayEngine>ScaledArrayEngine</linkto> and 00238 // <linkto class=RetypedArrayEngine>RetypedArrayEngine</linkto> 00239 // are two examples of how to derive a class from this base class. 00240 // Note that ScaledArrayEngine does not need to implement functions 00241 // dealing with shapes, because it can use them from this base class. 00242 // On the other hand they need to be implemented in RetypedArrayEngine. 00243 // </example> 00244 00245 // <motivation> 00246 // This base class implements several functions making the implementation 00247 // of derived classes simpler. Many details are implemented here, so often 00248 // only the basic mapping functions (get, put) need to be implemented 00249 // in a derived class. 00250 // </motivation> 00251 00252 // <templating arg=VirtualType> 00253 // <li> default constructor 00254 // <li> copy constructor 00255 // <li> assignment operator 00256 // <li> <src>static String dataTypeId(); // unique name of the class</src> 00257 // </templating> 00258 // <templating arg=StoredType> 00259 // <li> Default constructor 00260 // <li> Copy constructor 00261 // <li> Assignment operator 00262 // </templating> 00263 00264 00265 template<class VirtualType, class StoredType> class BaseMappedArrayEngine : public VirtualColumnEngine, public VirtualArrayColumn<VirtualType> 00266 { 00267 public: 00268 // Get the virtual column name. 00269 const String& virtualName() const; 00270 00271 // Get the stored column name. 00272 const String& storedName() const; 00273 00274 // The column is writable if the underlying stored column is writable. 00275 virtual Bool isWritable() const; 00276 00277 protected: 00278 00279 // Construct an engine to convert the virtual column to the stored column. 00280 // StoredColumnName is the name of the column where the converted 00281 // data will be put and must have data type StoredType. 00282 // The virtual column using this engine must have data type VirtualType. 00283 // By default the virtual column is assumed to be writable. 00284 // Use setWritable to unset it. 00285 BaseMappedArrayEngine (const String& virtualColumnName, 00286 const String& storedColumnName); 00287 00288 // Destructor is mandatory. 00289 ~BaseMappedArrayEngine(); 00290 00291 // The default constructor is required for reconstruction of the 00292 // engine when a table is read back. 00293 BaseMappedArrayEngine(); 00294 00295 // Copy constructor is only used by copy constructor of derived classes. 00296 // (so it is made protected). 00297 BaseMappedArrayEngine 00298 (const BaseMappedArrayEngine<VirtualType, StoredType>&); 00299 00300 // Set if the column is writable or not. 00301 void setWritable (Bool isWritable); 00302 00303 // Set the virtual and stored column name. 00304 void setNames (const String& virtualName, const String& storedName); 00305 00306 // Give access to the stored column. 00307 // This can be used by the derived classes to get/put data. 00308 inline ArrayColumn<StoredType>& column(); 00309 00310 // Create the column object for the array column in this engine. 00311 // It will check if the given column name matches the virtual 00312 // column name. This assures that the engine is bound to the 00313 // correct column. 00314 virtual DataManagerColumn* makeIndArrColumn (const String& columnName, 00315 int dataType, 00316 const String& dataTypeId); 00317 00318 // Initialize the object for a new table. 00319 // It defines a virtual column keyword telling the stored column name. 00320 // Initially the table has the given number of rows. 00321 // A derived class can have its own create function, but that should 00322 // always call this create function. 00323 virtual void create (uInt initialNrrow); 00324 00325 // Preparing consists of setting the writable switch and 00326 // adding the initial number of rows in case of create. 00327 // It reads the stored column name from the virtual column keywords. 00328 // A derived class can have its own prepare function, but that should 00329 // always call this prepare function. 00330 virtual void prepare(); 00331 00332 // Do the 2 stages of the prepare (define columns and adding rows). 00333 // <group> 00334 void prepare1(); 00335 void prepare2(); 00336 // </group> 00337 00338 // Rows are added to the end of the table. 00339 // If the virtual column has FixedShape arrays and the stored not, 00340 // the shape in each stored row will be set. 00341 // This assures that the arrays are properly defined in each row, 00342 // so putSlice can be used without problems. 00343 // <br>The second version is used by prepare2, because in case a column is 00344 // added to an already existing table, table.nrow() gives the existing 00345 // number of columns instead of 0. 00346 // <group> 00347 virtual void addRow (uInt nrrow); 00348 virtual void addRowInit (uInt startRow, uInt nrrow); 00349 // </group> 00350 00351 // Set the shape of the FixedShape arrays in the column. 00352 // This function only gets called if the column has FixedShape arrays. 00353 // The shape gets saved and used to set the shape of the arrays 00354 // in the stored in case the stored has non-FixedShape arrays. 00355 // This implementation assumes the shape of virtual and stored arrays 00356 // are the same. If not, it has to be overidden in a derived class. 00357 virtual void setShapeColumn (const IPosition& shape); 00358 00359 // Define the shape of the array in the given row. 00360 // It will define the shape of the (underlying) array. 00361 // This implementation assumes the shape of virtual and stored arrays 00362 // are the same. If not, it has to be overidden in a derived class. 00363 virtual void setShape (uInt rownr, const IPosition& shape); 00364 00365 // Test if the (underlying) array is defined in the given row. 00366 virtual Bool isShapeDefined (uInt rownr); 00367 00368 // Get the dimensionality of the (underlying) array in the given row. 00369 // This implementation assumes the dimensionality of virtual and 00370 // stored arrays are the same. If not, it has to be overidden in a 00371 // derived class. 00372 virtual uInt ndim (uInt rownr); 00373 00374 // Get the shape of the (underlying) array in the given row. 00375 // This implementation assumes the shape of virtual and stored arrays 00376 // are the same. If not, it has to be overidden in a derived class. 00377 virtual IPosition shape (uInt rownr); 00378 00379 // The data manager can handle changing the shape of an existing array 00380 // when the underlying stored column can do it. 00381 virtual Bool canChangeShape() const; 00382 00383 // Make a table column object for the given column. 00384 // This has to be used in the create function, otherwise it could not 00385 // create a TableColumn object to store data in the column keywords. 00386 TableColumn makeTableColumn (const String& columnName); 00387 00388 // Get an array in the given row. 00389 // This will scale and offset from the underlying array. 00390 virtual void getArray (uInt rownr, Array<VirtualType>& array); 00391 00392 // Put an array in the given row. 00393 // This will scale and offset to the underlying array. 00394 virtual void putArray (uInt rownr, const Array<VirtualType>& array); 00395 00396 // Get a section of the array in the given row. 00397 // This will scale and offset from the underlying array. 00398 virtual void getSlice (uInt rownr, const Slicer& slicer, 00399 Array<VirtualType>& array); 00400 00401 // Put into a section of the array in the given row. 00402 // This will scale and offset to the underlying array. 00403 virtual void putSlice (uInt rownr, const Slicer& slicer, 00404 const Array<VirtualType>& array); 00405 00406 // Get an entire column. 00407 // This will scale and offset from the underlying array. 00408 virtual void getArrayColumn (Array<VirtualType>& array); 00409 00410 // Put an entire column. 00411 // This will scale and offset to the underlying array. 00412 virtual void putArrayColumn (const Array<VirtualType>& array); 00413 00414 // Get some array values in the column. 00415 // This will scale and offset from the underlying array. 00416 virtual void getArrayColumnCells (const RefRows& rownrs, 00417 Array<VirtualType>& data); 00418 00419 // Put some array values in the column. 00420 // This will scale and offset to the underlying array. 00421 virtual void putArrayColumnCells (const RefRows& rownrs, 00422 const Array<VirtualType>& data); 00423 00424 // Get a section of all arrays in the column. 00425 // This will scale and offset from the underlying array. 00426 void getColumnSlice (const Slicer& slicer, Array<VirtualType>& array); 00427 00428 // Put a section of all arrays in the column. 00429 // This will scale and offset to the underlying array. 00430 void putColumnSlice (const Slicer& slicer, const Array<VirtualType>& array); 00431 00432 // Get a section of some arrays in the column. 00433 // This will scale and offset from the underlying array. 00434 virtual void getColumnSliceCells (const RefRows& rownrs, 00435 const Slicer& slicer, 00436 Array<VirtualType>& data); 00437 00438 // Put into a section of some arrays in the column. 00439 // This will scale and offset to the underlying array. 00440 virtual void putColumnSliceCells (const RefRows& rownrs, 00441 const Slicer& slicer, 00442 const Array<VirtualType>& data); 00443 00444 // Map the virtual shape to the stored shape. 00445 // By default is returns the virtual shape. 00446 virtual IPosition getStoredShape (uInt rownr, 00447 const IPosition& virtualShape); 00448 00449 // Map the slicer for a virtual shape to a stored shape. 00450 // By default it returns the virtual input slicer. 00451 virtual Slicer getStoredSlicer (const Slicer& virtualSlicer) const; 00452 00453 // Map StoredType array to VirtualType array. 00454 // This is meant when reading an array from the stored column. 00455 // The default implementation throws an exception. 00456 virtual void mapOnGet (Array<VirtualType>& array, 00457 const Array<StoredType>& stored); 00458 00459 // Map Bool array to bit flags array. 00460 // This is meant when writing an array into the stored column. 00461 // The default implementation throws an exception. 00462 virtual void mapOnPut (const Array<VirtualType>& array, 00463 Array<StoredType>& stored); 00464 00465 00466 private: 00467 // Assignment is not needed and therefore forbidden 00468 // (so it is made private and not implemented). 00469 BaseMappedArrayEngine<VirtualType, StoredType>& operator= 00470 (const BaseMappedArrayEngine<VirtualType, StoredType>&); 00471 00472 00473 //# Now define the data members. 00474 String virtualName_p; //# virtual column name 00475 String storedName_p; //# stored column name 00476 Bool isWritable_p; //# is virtual column writable? 00477 Bool tempWritable_p; //# True = create phase, so column 00478 //# is temporarily writable 00479 //# False = asks stored column 00480 uInt initialNrrow_p; //# initial #rows in case of create 00481 Bool arrayIsFixed_p; //# True = virtual is FixedShape array 00482 IPosition shapeFixed_p; //# shape in case FixedShape array 00483 ArrayColumn<StoredType>* column_p; //# the stored column 00484 }; 00485 00486 00487 00488 template<class VirtualType, class StoredType> 00489 inline const String& 00490 BaseMappedArrayEngine<VirtualType, StoredType>::virtualName() const 00491 { return virtualName_p; } 00492 00493 template<class VirtualType, class StoredType> 00494 inline const String& 00495 BaseMappedArrayEngine<VirtualType, StoredType>::storedName() const 00496 { return storedName_p; } 00497 00498 template<class VirtualType, class StoredType> 00499 inline void 00500 BaseMappedArrayEngine<VirtualType, StoredType>::setNames 00501 (const String& virtualName, const String& storedName) 00502 { 00503 virtualName_p = virtualName; 00504 storedName_p = storedName; 00505 } 00506 00507 template<class VirtualType, class StoredType> 00508 inline void 00509 BaseMappedArrayEngine<VirtualType, StoredType>::setWritable (Bool isWritable) 00510 { isWritable_p = isWritable; } 00511 00512 template<class VirtualType, class StoredType> 00513 inline ArrayColumn<StoredType>& 00514 BaseMappedArrayEngine<VirtualType, StoredType>::column() 00515 { return *column_p; } 00516 00517 00518 00519 } //# NAMESPACE CASACORE - END 00520 00521 #ifndef CASACORE_NO_AUTO_TEMPLATES 00522 #include <casacore/tables/DataMan/BaseMappedArrayEngine.tcc> 00523 #endif //# CASACORE_NO_AUTO_TEMPLATES 00524 #endif