casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
ISMColumn.h
Go to the documentation of this file.
00001 //# ISMColumn.h: A Column in the Incremental Storage Manager
00002 //# Copyright (C) 1996,1997,1998,1999,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: ISMColumn.h 20551 2009-03-25 00:11:33Z Malte.Marquarding $
00027 
00028 #ifndef TABLES_ISMCOLUMN_H
00029 #define TABLES_ISMCOLUMN_H
00030 
00031 
00032 //# Includes
00033 #include <casa/aips.h>
00034 #include <tables/Tables/StManColumn.h>
00035 #include <tables/Tables/ISMBase.h>
00036 #include <casa/Arrays/IPosition.h>
00037 #include <casa/Containers/Block.h>
00038 #include <casa/Utilities/Compare.h>
00039 #include <casa/OS/Conversion.h>
00040 
00041 namespace casa { //# NAMESPACE CASA - BEGIN
00042 
00043 //# Forward declarations
00044 class ISMBucket;
00045 
00046 
00047 // <summary>
00048 // A Column in the Incremental Storage Manager.
00049 // </summary>
00050 
00051 // <use visibility=local>
00052 
00053 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
00054 // </reviewed>
00055 
00056 // <prerequisite>
00057 //# Classes you should understand before using this one.
00058 //   <li> <linkto class=ISMBase>ISMBase</linkto>
00059 // </prerequisite>
00060 
00061 // <etymology>
00062 // ISMColumn represents a Column in the Incremental Storage Manager.
00063 // </etymology>
00064 
00065 // <synopsis>
00066 // ISMColumn handles the access to a column containing scalars or direct
00067 // arrays of the various data types. It uses class <linkto class=ISMBucket>
00068 // ISMBucket</linkto> to get and put the data into the correct bucket.
00069 // When the value does not fit in the bucket, the bucket is split
00070 // and the new bucket is added to the storage manager.
00071 // <p>
00072 // The object maintains a variable indicating the last row ever put.
00073 // This is used to decide if a put of a value is valid until the
00074 // end of the table or for that one row only. In this way it does not
00075 // make any difference if rows are added before or after a value is put
00076 // <br>
00077 // A value put before or at the last row ever put will only affect that
00078 // one row. The rows before and after it keep their original value. If
00079 // needed that value is copied.
00080 // <p>
00081 // To optimize (especially sequential) access to the column, ISMColumn
00082 // maintains the last value gotten and the rows for which it is valid.
00083 // In this way a get does not need to access the data in the bucket.
00084 // <p>
00085 // ISMColumn use the static conversion functions in the
00086 // <linkto class=Conversion>Conversion</linkto> framework to
00087 // get/put the data in external format (be it canonical or local).
00088 // Most data types are fixed length, but some are variable length
00089 // (e.g. String). In external format variable length data is preceeded
00090 // by its total length (which includes the length itself). This makes
00091 // it possible to get the length of a data value without having to
00092 // interpret it, which is easy when (re)moving a value. For this reason
00093 // ISMColumn contains its own conversion functions for Strings.
00094 // <p>
00095 // ISMColumn also acts as the base class for more specialized ISM
00096 // column classes (i.e. <linkto class=ISMIndColumn>ISMIndColumn</linkto>
00097 // for indirect columns).
00098 // In this way <linkto class=ISMBase>ISMBase</linkto> can hold a
00099 // block of <src>ISMColumn*</src> for any column. Furthermore
00100 // <src>ISMColumn</src> contains the hooks to allow a derived class
00101 // to use other ISMColumn functions (e.g. there are "action" functions
00102 // for a derived class to react on the duplication or removal of
00103 // a data value (e.g. due to a bucket split).
00104 // </synopsis> 
00105 
00106 // <motivation>
00107 // ISMColumn encapsulates all operations on an ISM Column.
00108 // </motivation>
00109 
00110 //# <todo asof="$DATE:$">
00111 //# A List of bugs, limitations, extensions or planned refinements.
00112 //# </todo>
00113 
00114 
00115 class ISMColumn : public StManColumn
00116 {
00117 public:
00118     // Create a ISMColumn object with the given parent.
00119     // It initializes the various variables.
00120     // It keeps the pointer to its parent (but does not own it).
00121     ISMColumn (ISMBase* parent, int dataType, uInt colnr);
00122 
00123     ~ISMColumn();
00124 
00125     // Set the shape of an array in the column.
00126     virtual void setShapeColumn (const IPosition& shape);
00127 
00128     // Get the dimensionality of the item in the given row.
00129     // This is the same for all rows.
00130     virtual uInt ndim (uInt rownr);
00131 
00132     // Get the shape of the array in the given row.
00133     // This is the same for all rows.
00134     virtual IPosition shape (uInt rownr);
00135 
00136     // Let the column object initialize itself for a newly created table.
00137     // This is meant for a derived class.
00138     virtual void doCreate (ISMBucket*);
00139 
00140     // Let the column object initialize itself for an existing table.
00141     virtual void getFile (uInt nrrow);
00142 
00143     // Flush and optionally fsync the data.
00144     // This is meant for a derived class.
00145     virtual Bool flush (uInt nrrow, Bool fsync);
00146 
00147     // Resync the storage manager with the new file contents.
00148     // It resets the last rownr put.
00149     void resync (uInt nrrow);
00150 
00151     // Let the column reopen its data files for read/write access.
00152     virtual void reopenRW();
00153 
00154     // Get a scalar value in the given row.
00155     // <group>
00156     virtual void getBoolV     (uInt rownr, Bool* dataPtr);
00157     virtual void getuCharV    (uInt rownr, uChar* dataPtr);
00158     virtual void getShortV    (uInt rownr, Short* dataPtr);
00159     virtual void getuShortV   (uInt rownr, uShort* dataPtr);
00160     virtual void getIntV      (uInt rownr, Int* dataPtr);
00161     virtual void getuIntV     (uInt rownr, uInt* dataPtr);
00162     virtual void getfloatV    (uInt rownr, float* dataPtr);
00163     virtual void getdoubleV   (uInt rownr, double* dataPtr);
00164     virtual void getComplexV  (uInt rownr, Complex* dataPtr);
00165     virtual void getDComplexV (uInt rownr, DComplex* dataPtr);
00166     virtual void getStringV   (uInt rownr, String* dataPtr);
00167     // </group>
00168 
00169     // Put a scalar value in the given row.
00170     // <group>
00171     virtual void putBoolV     (uInt rownr, const Bool* dataPtr);
00172     virtual void putuCharV    (uInt rownr, const uChar* dataPtr);
00173     virtual void putShortV    (uInt rownr, const Short* dataPtr);
00174     virtual void putuShortV   (uInt rownr, const uShort* dataPtr);
00175     virtual void putIntV      (uInt rownr, const Int* dataPtr);
00176     virtual void putuIntV     (uInt rownr, const uInt* dataPtr);
00177     virtual void putfloatV    (uInt rownr, const float* dataPtr);
00178     virtual void putdoubleV   (uInt rownr, const double* dataPtr);
00179     virtual void putComplexV  (uInt rownr, const Complex* dataPtr);
00180     virtual void putDComplexV (uInt rownr, const DComplex* dataPtr);
00181     virtual void putStringV   (uInt rownr, const String* dataPtr);
00182     // </group>
00183 
00184     // Get the scalar values in the entire column.
00185     // The buffer pointed to by dataPtr has to have the correct length.
00186     // (which is guaranteed by the ScalarColumn getColumn function).
00187     // <group>
00188     virtual void getScalarColumnBoolV     (Vector<Bool>* dataPtr);
00189     virtual void getScalarColumnuCharV    (Vector<uChar>* dataPtr);
00190     virtual void getScalarColumnShortV    (Vector<Short>* dataPtr);
00191     virtual void getScalarColumnuShortV   (Vector<uShort>* dataPtr);
00192     virtual void getScalarColumnIntV      (Vector<Int>* dataPtr);
00193     virtual void getScalarColumnuIntV     (Vector<uInt>* dataPtr);
00194     virtual void getScalarColumnfloatV    (Vector<float>* dataPtr);
00195     virtual void getScalarColumndoubleV   (Vector<double>* dataPtr);
00196     virtual void getScalarColumnComplexV  (Vector<Complex>* dataPtr);
00197     virtual void getScalarColumnDComplexV (Vector<DComplex>* dataPtr);
00198     virtual void getScalarColumnStringV   (Vector<String>* dataPtr);
00199     // </group>
00200 
00201     // Put the scalar values into the entire column.
00202     // The buffer pointed to by dataPtr has to have the correct length.
00203     // (which is guaranteed by the ScalarColumn putColumn function).
00204     // <group>
00205     virtual void putScalarColumnBoolV     (const Vector<Bool>* dataPtr);
00206     virtual void putScalarColumnuCharV    (const Vector<uChar>* dataPtr);
00207     virtual void putScalarColumnShortV    (const Vector<Short>* dataPtr);
00208     virtual void putScalarColumnuShortV   (const Vector<uShort>* dataPtr);
00209     virtual void putScalarColumnIntV      (const Vector<Int>* dataPtr);
00210     virtual void putScalarColumnuIntV     (const Vector<uInt>* dataPtr);
00211     virtual void putScalarColumnfloatV    (const Vector<float>* dataPtr);
00212     virtual void putScalarColumndoubleV   (const Vector<double>* dataPtr);
00213     virtual void putScalarColumnComplexV  (const Vector<Complex>* dataPtr);
00214     virtual void putScalarColumnDComplexV (const Vector<DComplex>* dataPtr);
00215     virtual void putScalarColumnStringV   (const Vector<String>* dataPtr);
00216     // </group>
00217 
00218     // Get the scalar values in some cells of the column.
00219     // The buffer pointed to by dataPtr has to have the correct length.
00220     // (which is guaranteed by the ScalarColumn getColumnCells function).
00221     // The default implementation loops through all rows.
00222     // <group>
00223     virtual void getScalarColumnCellsBoolV     (const RefRows& rownrs,
00224                                                 Vector<Bool>* dataPtr);
00225     virtual void getScalarColumnCellsuCharV    (const RefRows& rownrs,
00226                                                 Vector<uChar>* dataPtr);
00227     virtual void getScalarColumnCellsShortV    (const RefRows& rownrs,
00228                                                 Vector<Short>* dataPtr);
00229     virtual void getScalarColumnCellsuShortV   (const RefRows& rownrs,
00230                                                 Vector<uShort>* dataPtr);
00231     virtual void getScalarColumnCellsIntV      (const RefRows& rownrs,
00232                                                 Vector<Int>* dataPtr);
00233     virtual void getScalarColumnCellsuIntV     (const RefRows& rownrs,
00234                                                 Vector<uInt>* dataPtr);
00235     virtual void getScalarColumnCellsfloatV    (const RefRows& rownrs,
00236                                                 Vector<float>* dataPtr);
00237     virtual void getScalarColumnCellsdoubleV   (const RefRows& rownrs,
00238                                                 Vector<double>* dataPtr);
00239     virtual void getScalarColumnCellsComplexV  (const RefRows& rownrs,
00240                                                 Vector<Complex>* dataPtr);
00241     virtual void getScalarColumnCellsDComplexV (const RefRows& rownrs,
00242                                                 Vector<DComplex>* dataPtr);
00243     virtual void getScalarColumnCellsStringV   (const RefRows& rownrs,
00244                                                 Vector<String>* dataPtr);
00245     // </group>
00246 
00247     // Get an array value in the given row.
00248     // <group>
00249     virtual void getArrayBoolV     (uInt rownr, Array<Bool>* dataPtr);
00250     virtual void getArrayuCharV    (uInt rownr, Array<uChar>* dataPtr);
00251     virtual void getArrayShortV    (uInt rownr, Array<Short>* dataPtr);
00252     virtual void getArrayuShortV   (uInt rownr, Array<uShort>* dataPtr);
00253     virtual void getArrayIntV      (uInt rownr, Array<Int>* dataPtr);
00254     virtual void getArrayuIntV     (uInt rownr, Array<uInt>* dataPtr);
00255     virtual void getArrayfloatV    (uInt rownr, Array<float>* dataPtr);
00256     virtual void getArraydoubleV   (uInt rownr, Array<double>* dataPtr);
00257     virtual void getArrayComplexV  (uInt rownr, Array<Complex>* dataPtr);
00258     virtual void getArrayDComplexV (uInt rownr, Array<DComplex>* dataPtr);
00259     virtual void getArrayStringV   (uInt rownr, Array<String>* dataPtr);
00260     // </group>
00261 
00262     // Put an array value in the given row.
00263     // <group>
00264     virtual void putArrayBoolV     (uInt rownr, const Array<Bool>* dataPtr);
00265     virtual void putArrayuCharV    (uInt rownr, const Array<uChar>* dataPtr);
00266     virtual void putArrayShortV    (uInt rownr, const Array<Short>* dataPtr);
00267     virtual void putArrayuShortV   (uInt rownr, const Array<uShort>* dataPtr);
00268     virtual void putArrayIntV      (uInt rownr, const Array<Int>* dataPtr);
00269     virtual void putArrayuIntV     (uInt rownr, const Array<uInt>* dataPtr);
00270     virtual void putArrayfloatV    (uInt rownr, const Array<float>* dataPtr);
00271     virtual void putArraydoubleV   (uInt rownr, const Array<double>* dataPtr);
00272     virtual void putArrayComplexV  (uInt rownr, const Array<Complex>* dataPtr);
00273     virtual void putArrayDComplexV (uInt rownr, const Array<DComplex>* dataPtr);
00274     virtual void putArrayStringV   (uInt rownr, const Array<String>* dataPtr);
00275     // </group>
00276 
00277     // Add (newNrrow-oldNrrow) rows to the column and initialize
00278     // the new rows when needed.
00279     virtual void addRow (uInt newNrrow, uInt oldNrrow);
00280 
00281     // Remove the given row in the bucket from the column.
00282     void remove (uInt bucketRownr, ISMBucket* bucket, uInt bucketNrrow,
00283                  uInt newNrrow);
00284 
00285     // Get the function needed to read/write a uInt from/to external format.
00286     // This is used by other classes to read the length of a variable
00287     // data value.
00288     // <group>
00289     static Conversion::ValueFunction* getReaduInt  (Bool asCanonical);
00290     static Conversion::ValueFunction* getWriteuInt (Bool asCanonical);
00291     // </group>
00292 
00293     // Give a derived class the opportunity to react on the duplication
00294     // of a value. It is used by ISMIndColumn.
00295     virtual void handleCopy (uInt rownr, const char* value);
00296 
00297     // Give a derived class the opportunity to react on the removal
00298     // of a value. It is used by ISMIndColumn.
00299     virtual void handleRemove (uInt rownr, const char* value);
00300 
00301     // Get the fixed length of the data value in a cell of this column
00302     // (0 = variable length).
00303     uInt getFixedLength() const;
00304 
00305     // Get the nr of elements in this data value.
00306     uInt nelements() const;
00307 
00308 
00309 protected:
00310     // Test if the last value is invalid for this row.
00311     int isLastValueInvalid (Int rownr) const;
00312 
00313     // Get the value for this row.
00314     // Set the cache if the flag is set.
00315     void getValue (uInt rownr, void* value, Bool setCache);
00316 
00317     // Put the value for this row.
00318     void putValue (uInt rownr, const void* value);
00319 
00320     //# Declare member variables.
00321     // Pointer to the parent storage manager.
00322     ISMBase*          stmanPtr_p;
00323     // Length of column cell value in storage format (0 = variable length).
00324     // If 0, the value is always preceeded by a uInt giving the length.
00325     uInt              fixedLength_p;
00326     // Column sequence number of this column.
00327     uInt              colnr_p;
00328     // The shape of the column.
00329     IPosition         shape_p;
00330     // Number of elements in a value for this column.
00331     uInt              nrelem_p;
00332     // Number of values to be copied.
00333     // Normally this is nrelem_p, but for complex types it is 2*nrelem_p.
00334     // When local format is used, it is the number of bytes.
00335     uInt              nrcopy_p;
00336     // Cache for interval for which last value read is valid.
00337     // The last value is valid for startRow_p till endRow_p (inclusive).
00338     Int               startRow_p;
00339     Int               endRow_p;
00340     void*             lastValue_p;
00341     // The last row for which a value has been put.
00342     uInt              lastRowPut_p;
00343     // The size of the data type in local format.
00344     uInt              typeSize_p;
00345     // Pointer to a convert function for writing.
00346     Conversion::ValueFunction* writeFunc_p;
00347     // Pointer to a convert function for reading.
00348     Conversion::ValueFunction* readFunc_p;
00349     // Pointer to a compare function.
00350     ObjCompareFunc*   compareFunc_p;
00351 
00352 
00353 private:
00354     // Forbid copy constructor.
00355     ISMColumn (const ISMColumn&);
00356 
00357     // Forbid assignment.
00358     ISMColumn& operator= (const ISMColumn&);
00359 
00360     // Initialize part of the object.
00361     // It is used by doCreate and getFile.
00362     void init();
00363 
00364     // Clear the object (used by destructor and init).
00365     void clear();
00366 
00367     // Put the value in all buckets from the given row on.
00368     void putFromRow (uInt rownr, const char* data, uInt lenData);
00369 
00370     // Put a data value into the bucket.
00371     // When it is at the first row of the bucket, it replaces the value.
00372     // Otherwise it is added.
00373     void putData (ISMBucket* bucket, uInt bucketStartRow,
00374                   uInt bucketNrrow, uInt bucketRownr,
00375                   const char* data, uInt lenData,
00376                   Bool afterLastRow, Bool canSplit);
00377 
00378     // Replace a value at the given offset in the bucket.
00379     // If the bucket is too small, it will be split (if allowed).
00380     void replaceData (ISMBucket* bucket, uInt bucketStartRow,
00381                       uInt bucketNrrow, uInt bucketRownr, uInt& offset,
00382                       const char* data, uInt lenData, Bool canSplit = True);
00383 
00384     // Add a value at the given index in the bucket.
00385     // If the bucket is too small, it will be split (if allowed).
00386     Bool addData (ISMBucket* bucket, uInt bucketStartRow,
00387                   uInt bucketNrrow, uInt bucketRownr, uInt inx,
00388                   const char* data, uInt lenData,
00389                   Bool afterLastRow = False, Bool canSplit = True);
00390 
00391     // Handle the duplicated values after a bucket split.
00392     void handleSplit (ISMBucket& bucket, const Block<Bool>& duplicated);
00393 
00394     // Compare the values.
00395     virtual Bool compareValue (const void* val1, const void* val2) const;
00396 
00397     // Handle a String in copying to/from external format.
00398     // <group>
00399     static uInt fromString (void* out, const void* in, uInt n,
00400                             Conversion::ValueFunction* writeLeng);
00401     static uInt toString (void* out, const void* in, uInt n,
00402                           Conversion::ValueFunction* readLeng);
00403     static uInt writeStringBE (void* out, const void* in, uInt n);
00404     static uInt readStringBE (void* out, const void* in, uInt n);
00405     static uInt writeStringLE (void* out, const void* in, uInt n);
00406     static uInt readStringLE (void* out, const void* in, uInt n);
00407     // </group>
00408 };
00409 
00410 
00411 inline int ISMColumn::isLastValueInvalid (Int rownr) const
00412 {
00413     return rownr < startRow_p  ||  rownr > endRow_p;
00414 }
00415 
00416 inline uInt ISMColumn::getFixedLength() const
00417 {
00418     return fixedLength_p;
00419 }
00420 
00421 inline uInt ISMColumn::nelements() const
00422 {
00423     return nrelem_p;
00424 }
00425 
00426 
00427 
00428 } //# NAMESPACE CASA - END
00429 
00430 #endif