BaseMappedArrayEngine.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1