casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
BaseMappedArrayEngine.h
Go to the documentation of this file.
1 //# BaseMappedArrayEngine.h: Abstract virtual column engine for virtual->stored mapping
2 //# Copyright (C) 1995,1996,1997,1999,2001,2002
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef TABLES_BASEMAPPEDARRAYENGINE_H
29 #define TABLES_BASEMAPPEDARRAYENGINE_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 template<class T> class ArrayColumn;
41 class TableColumn;
42 
43 
44 // <summary>
45 // Templated virtual column engine for a table array of any type.
46 // </summary>
47 
48 // <use visibility=export>
49 
50 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
51 // </reviewed>
52 
53 // <prerequisite>
54 //# Classes you should understand before using this one.
55 // <li> <linkto class=VirtualColumnEngine>VirtualColumnEngine</linkto>
56 // <li> <linkto class=VirtualArrayColumn>VirtualArrayColumn</linkto>
57 // </prerequisite>
58 
59 // <etymology>
60 // BaseMappedArrayEngine contains for the 1-1 mapping of a virtual
61 // column to a stored column (both containing arrays).
62 // </etymology>
63 
64 // <synopsis>
65 // BaseMappedArrayEngine is an abstract base class for virtual column engines
66 // which map data from the arrays in the virtual column to
67 // the arrays in the stored column. Note the the stored column does not need
68 // to be stored; it can be another virtual column, but usually it will be a
69 // stored column.
70 // Examples of classes using this base class are
71 // <linkto class=ScaledArrayEngine>ScaledArrayEngine</linkto> and
72 // <linkto class=RetypedArrayEngine>RetypedArrayEngine</linkto>.
73 //
74 // The virtual column has to be bound to the virtual column engine used
75 // for it. The stored column will usually be bound to a storage manager,
76 // but any other suitable data manager is possible. E.g. it is
77 // possible to use <src>MappedArrayEngine<StokesVector,float></src>
78 // to map a StokesVector to a float column, which in its turn uses
79 // <src>ScaledArrayEngine<float,Int></src> to store it as integers.
80 // Note that the names of the virtual and stored column have to be different,
81 // otherwise the table system cannot distinguish them.
82 //
83 // This base class does several tasks for the derived classes.
84 // The main one is to keep and handle the information about the virtual
85 // and stored column. The name of the stored column is written as a keyword
86 // in the virtual column. In this way the stored column is known when
87 // a table is read back. It also creates <src>(RO)ArrayColumn<T></src>
88 // objects to access the stored column. The function roColumn gives
89 // read access, while rwColumn gives write access.
90 //
91 // An engine object should be used for one column only, because the stored
92 // column name is part of the engine. If it would be used for more than
93 // one column, they would all share the same stored column.
94 // When the engine is bound to a column, it is checked if the name
95 // of that column matches the given virtual column name.
96 //
97 // The engine can be used for a column containing any kind of array
98 // (thus direct or indirect, fixed or variable shaped)) as long as the
99 // virtual array can be stored in the stored array. Thus a fixed shaped
100 // virtual can use a variable shaped stored, but not vice versa.
101 // A fixed shape indirect virtual can use a stored with direct arrays.
102 //
103 // The DataManager framework contains various virtual functions.
104 // This class implements several, but not all of them. Furthermore
105 // some implementations may not be optimal or correct for derived classes.
106 // Hereafter follows a list of functions which may need implementation
107 // in derived classes. The classes mentioned in the examples below show
108 // implementations of these functions.
109 // <ul>
110 // <li>
111 // The following (virtual) functions have to be implemented:
112 // <dl>
113 // <dt><src>
114 // ~... (the destructor)
115 // </src>
116 // <dt><src>
117 // DataManager* clone() const;
118 // </src>
119 // <dt><src>
120 // String dataManagerType() const;
121 // </src>
122 // <dt><src>
123 // static void registerClass();
124 // </src>
125 // <dt><src>
126 // static DataManager* makeObject (const String& dataManagerType);
127 // </src>
128 // <dt><src>
129 // void getArray (rownr_t rownr, Array<T>& data);
130 // </src>
131 // <dt><src>
132 // void putArray (rownr_t rownr, const Array<T>& data);
133 // </src>
134 // (only if the virtual column is writable).
135 // </dl>
136 // <li>
137 // For efficiency reasons it could be better to implement the following
138 // functions:
139 // <dl>
140 // <dt><src>
141 // void getSlice (rownr_t rownr, const Slicer& slicer, Array<T>& data);
142 // </src>
143 // <dt><src>
144 // void putSlice (rownr_t rownr, const Slicer& slicer,
145 // const Array<T>& data);
146 // </src>
147 // <dt><src>
148 // void getArrayColumn (Array<T>& data);
149 // </src>
150 // <dt><src>
151 // void putArrayColumn (const Array<T>& data);
152 // </src>
153 // <dt><src>
154 // void getColumnSlice (const Slicer& slicer, Array<T>& data);
155 // </src>
156 // <dt><src>
157 // void putColumnSlice (const Slicer& slicer, const Array<T>& data);
158 // </src>
159 // </dl>
160 // <li>
161 // The following functions have to be implemented when the shapes
162 // of the virtual and stored arrays are not the same.
163 // <dl>
164 // <dt><src>
165 // void setShapeColumn (const IPosition& shape);
166 // </src>
167 // <dt><src>
168 // void setShape (rownr_t rownr, const IPosition& shape);
169 // </src>
170 // <dt><src>
171 // uInt ndim (rownr_t rownr);
172 // </src>
173 // <dt><src>
174 // IPosition shape (rownr_t rownr);
175 // </src>
176 // </dl>
177 // <li>
178 // The following functions deal with the initialization and persistence
179 // of engine specific variables. When the class has variables of its
180 // own, these functions may need to be implemented. Implementations of
181 // create and prepare have to call the similar functions in this base class.
182 // <dl>
183 // <dt><src>
184 // void close (AipsIO& ios);
185 // </src>
186 // <dt><src>
187 // void create64 (rownr_t nrrow);
188 // </src>
189 // <dt><src>
190 // void open64 (rownr_t nrrow, AipsIO& ios);
191 // </src>
192 // <dt><src>
193 // void prepare();
194 // </src>
195 // </dl>
196 // <li>
197 // The following functions do not need to be declared and implemented
198 // in derived classes unless it is a very special case.
199 // <dl>
200 // <dt><src>
201 // String dataManagerName() const;
202 // </src>
203 // <dt><src>
204 // Bool canAddRow() const;
205 // </src>
206 // <dt><src>
207 // Bool canRemoveRow() const;
208 // </src>
209 // <dt><src>
210 // void addRow64 (rownr_t nrrow);
211 // </src>
212 // <dt><src>
213 // void removeRow64 (rownr_t rownr);
214 // </src>
215 // <dt><src>
216 // DataManagerColumn* makeDirArrColumn (const String& columnName,
217 // int dataType,
218 // const String& dataTypeId);
219 // </src>
220 // <dt><src>
221 // DataManagerColumn* makeIndArrColumn (const String& columnName,
222 // int dataType,
223 // const String& dataTypeId);
224 // </src>
225 // <dt><src>
226 // Bool isWritable() const;
227 // </src>
228 // <dt><src>
229 // Bool isShapeDefined (rownr_t rownr);
230 // </src>
231 // </dl>
232 // </ul>
233 // </synopsis>
234 
235 // <example>
236 // The derived classes
237 // <linkto class=ScaledArrayEngine>ScaledArrayEngine</linkto> and
238 // <linkto class=RetypedArrayEngine>RetypedArrayEngine</linkto>
239 // are two examples of how to derive a class from this base class.
240 // Note that ScaledArrayEngine does not need to implement functions
241 // dealing with shapes, because it can use them from this base class.
242 // On the other hand they need to be implemented in RetypedArrayEngine.
243 // </example>
244 
245 // <motivation>
246 // This base class implements several functions making the implementation
247 // of derived classes simpler. Many details are implemented here, so often
248 // only the basic mapping functions (get, put) need to be implemented
249 // in a derived class.
250 // </motivation>
251 
252 // <templating arg=VirtualType>
253 // <li> default constructor
254 // <li> copy constructor
255 // <li> assignment operator
256 // <li> <src>static String dataTypeId(); // unique name of the class</src>
257 // </templating>
258 // <templating arg=StoredType>
259 // <li> Default constructor
260 // <li> Copy constructor
261 // <li> Assignment operator
262 // </templating>
263 
264 
265 template<class VirtualType, class StoredType> class BaseMappedArrayEngine : public VirtualColumnEngine, public VirtualArrayColumn<VirtualType>
266 {
267 public:
268  // Get the virtual column name.
269  const String& virtualName() const;
270 
271  // Get the stored column name.
272  const String& storedName() const;
273 
274  // The column is writable if the underlying stored column is writable.
275  virtual Bool isWritable() const;
276 
277 protected:
278 
279  // Construct an engine to convert the virtual column to the stored column.
280  // StoredColumnName is the name of the column where the converted
281  // data will be put and must have data type StoredType.
282  // The virtual column using this engine must have data type VirtualType.
283  // By default the virtual column is assumed to be writable.
284  // Use setWritable to unset it.
285  BaseMappedArrayEngine (const String& virtualColumnName,
286  const String& storedColumnName);
287 
288  // Destructor is mandatory.
290 
291  // The default constructor is required for reconstruction of the
292  // engine when a table is read back.
294 
295  // Copy constructor is only used by copy constructor of derived classes.
296  // (so it is made protected).
299 
300  // Set if the column is writable or not.
301  void setWritable (Bool isWritable);
302 
303  // Set the virtual and stored column name.
304  void setNames (const String& virtualName, const String& storedName);
305 
306  // Give access to the stored column.
307  // This can be used by the derived classes to get/put data.
309 
310  // Create the column object for the array column in this engine.
311  // It will check if the given column name matches the virtual
312  // column name. This assures that the engine is bound to the
313  // correct column.
315  int dataType,
316  const String& dataTypeId);
317 
318  // Initialize the object for a new table.
319  // It defines a virtual column keyword telling the stored column name.
320  // Initially the table has the given number of rows.
321  // A derived class can have its own create function, but that should
322  // always call this create function.
323  virtual void create64 (rownr_t initialNrrow);
324 
325  // Preparing consists of setting the writable switch and
326  // adding the initial number of rows in case of create.
327  // It reads the stored column name from the virtual column keywords.
328  // A derived class can have its own prepare function, but that should
329  // always call this prepare function.
330  virtual void prepare();
331 
332  // Do the 2 stages of the prepare (define columns and adding rows).
333  // <group>
334  void prepare1();
335  void prepare2();
336  // </group>
337 
338  // Rows are added to the end of the table.
339  // If the virtual column has FixedShape arrays and the stored not,
340  // the shape in each stored row will be set.
341  // This assures that the arrays are properly defined in each row,
342  // so putSlice can be used without problems.
343  // <br>The second version is used by prepare2, because in case a column is
344  // added to an already existing table, table.nrow() gives the existing
345  // number of columns instead of 0.
346  // <group>
347  virtual void addRow64 (rownr_t nrrow);
348  virtual void addRowInit (rownr_t startRow, rownr_t nrrow);
349  // </group>
350 
351  // Set the shape of the FixedShape arrays in the column.
352  // This function only gets called if the column has FixedShape arrays.
353  // The shape gets saved and used to set the shape of the arrays
354  // in the stored in case the stored has non-FixedShape arrays.
355  // This implementation assumes the shape of virtual and stored arrays
356  // are the same. If not, it has to be overidden in a derived class.
357  virtual void setShapeColumn (const IPosition& shape);
358 
359  // Define the shape of the array in the given row.
360  // It will define the shape of the (underlying) array.
361  // This implementation assumes the shape of virtual and stored arrays
362  // are the same. If not, it has to be overidden in a derived class.
363  virtual void setShape (rownr_t rownr, const IPosition& shape);
364 
365  // Test if the (underlying) array is defined in the given row.
366  virtual Bool isShapeDefined (rownr_t rownr);
367 
368  // Get the dimensionality of the (underlying) array in the given row.
369  // This implementation assumes the dimensionality of virtual and
370  // stored arrays are the same. If not, it has to be overidden in a
371  // derived class.
372  virtual uInt ndim (rownr_t rownr);
373 
374  // Get the shape of the (underlying) array in the given row.
375  // This implementation assumes the shape of virtual and stored arrays
376  // are the same. If not, it has to be overidden in a derived class.
377  virtual IPosition shape (rownr_t rownr);
378 
379  // The data manager can handle changing the shape of an existing array
380  // when the underlying stored column can do it.
381  virtual Bool canChangeShape() const;
382 
383  // Make a table column object for the given column.
384  // This has to be used in the create function, otherwise it could not
385  // create a TableColumn object to store data in the column keywords.
386  TableColumn makeTableColumn (const String& columnName);
387 
388  // Get an array in the given row.
389  // This will scale and offset from the underlying array.
390  virtual void getArray (rownr_t rownr, Array<VirtualType>& array);
391 
392  // Put an array in the given row.
393  // This will scale and offset to the underlying array.
394  virtual void putArray (rownr_t rownr, const Array<VirtualType>& array);
395 
396  // Get a section of the array in the given row.
397  // This will scale and offset from the underlying array.
398  virtual void getSlice (rownr_t rownr, const Slicer& slicer,
399  Array<VirtualType>& array);
400 
401  // Put into a section of the array in the given row.
402  // This will scale and offset to the underlying array.
403  virtual void putSlice (rownr_t rownr, const Slicer& slicer,
404  const Array<VirtualType>& array);
405 
406  // Get an entire column.
407  // This will scale and offset from the underlying array.
408  virtual void getArrayColumn (Array<VirtualType>& array);
409 
410  // Put an entire column.
411  // This will scale and offset to the underlying array.
412  virtual void putArrayColumn (const Array<VirtualType>& array);
413 
414  // Get some array values in the column.
415  // This will scale and offset from the underlying array.
416  virtual void getArrayColumnCells (const RefRows& rownrs,
417  Array<VirtualType>& data);
418 
419  // Put some array values in the column.
420  // This will scale and offset to the underlying array.
421  virtual void putArrayColumnCells (const RefRows& rownrs,
422  const Array<VirtualType>& data);
423 
424  // Get a section of all arrays in the column.
425  // This will scale and offset from the underlying array.
426  void getColumnSlice (const Slicer& slicer, Array<VirtualType>& array);
427 
428  // Put a section of all arrays in the column.
429  // This will scale and offset to the underlying array.
430  void putColumnSlice (const Slicer& slicer, const Array<VirtualType>& array);
431 
432  // Get a section of some arrays in the column.
433  // This will scale and offset from the underlying array.
434  virtual void getColumnSliceCells (const RefRows& rownrs,
435  const Slicer& slicer,
436  Array<VirtualType>& data);
437 
438  // Put into a section of some arrays in the column.
439  // This will scale and offset to the underlying array.
440  virtual void putColumnSliceCells (const RefRows& rownrs,
441  const Slicer& slicer,
442  const Array<VirtualType>& data);
443 
444  // Map the virtual shape to the stored shape.
445  // By default is returns the virtual shape.
446  virtual IPosition getStoredShape (rownr_t rownr,
447  const IPosition& virtualShape);
448 
449  // Map the slicer for a virtual shape to a stored shape.
450  // By default it returns the virtual input slicer.
451  virtual Slicer getStoredSlicer (const Slicer& virtualSlicer) const;
452 
453  // Map StoredType array to VirtualType array.
454  // This is meant when reading an array from the stored column.
455  // The default implementation throws an exception.
456  virtual void mapOnGet (Array<VirtualType>& array,
457  const Array<StoredType>& stored);
458 
459  // Map Bool array to bit flags array.
460  // This is meant when writing an array into the stored column.
461  // The default implementation throws an exception.
462  virtual void mapOnPut (const Array<VirtualType>& array,
463  Array<StoredType>& stored);
464 
465 
466 private:
467  // Assignment is not needed and therefore forbidden
468  // (so it is made private and not implemented).
471 
472 
473  //# Now define the data members.
474  String virtualName_p; //# virtual column name
475  String storedName_p; //# stored column name
476  Bool isWritable_p; //# is virtual column writable?
477  Bool tempWritable_p; //# True = create phase, so column
478  //# is temporarily writable
479  //# False = asks stored column
480  rownr_t initialNrrow_p; //# initial #rows in case of create
481  Bool arrayIsFixed_p; //# True = virtual is FixedShape array
482  IPosition shapeFixed_p; //# shape in case FixedShape array
483  ArrayColumn<StoredType>* column_p; //# the stored column
484 };
485 
486 
487 
488 template<class VirtualType, class StoredType>
489 inline const String&
491  { return virtualName_p; }
492 
493 template<class VirtualType, class StoredType>
494 inline const String&
496  { return storedName_p; }
497 
498 template<class VirtualType, class StoredType>
499 inline void
501  (const String& virtualName, const String& storedName)
502 {
503  virtualName_p = virtualName;
504  storedName_p = storedName;
505 }
506 
507 template<class VirtualType, class StoredType>
508 inline void
510  { isWritable_p = isWritable; }
511 
512 template<class VirtualType, class StoredType>
515  { return *column_p; }
516 
517 
518 
519 } //# NAMESPACE CASACORE - END
520 
521 #ifndef CASACORE_NO_AUTO_TEMPLATES
522 #include <casacore/tables/DataMan/BaseMappedArrayEngine.tcc>
523 #endif //# CASACORE_NO_AUTO_TEMPLATES
524 #endif
A Vector of integers, for indexing into Array&lt;T&gt; objects.
Definition: IPosition.h:118
virtual Bool canChangeShape() const
The data manager can handle changing the shape of an existing array when the underlying stored column...
void setNames(const String &virtualName, const String &storedName)
Set the virtual and stored column name.
Abstract base class for virtual column handling.
Definition: VirtColEng.h:111
virtual void getColumnSliceCells(const RefRows &rownrs, const Slicer &slicer, Array< VirtualType > &data)
Get a section of some arrays in the column.
const String & virtualName() const
Get the virtual column name.
virtual void mapOnGet(Array< VirtualType > &array, const Array< StoredType > &stored)
Map StoredType array to VirtualType array.
ArrayColumn< StoredType > & column()
Give access to the stored column.
const String & columnName() const
Get rhe column name.
virtual void prepare()
Preparing consists of setting the writable switch and adding the initial number of rows in case of cr...
Abstract base class for a column in a data manager.
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition: ExprNode.h:1929
virtual void setShape(rownr_t rownr, const IPosition &shape)
Define the shape of the array in the given row.
Templated virtual column engine for a table array of any type.
virtual void getArrayColumnCells(const RefRows &rownrs, Array< VirtualType > &data)
Get some array values in the column.
virtual String dataTypeId() const
Return the data type Id of the column.
virtual void putArrayColumnCells(const RefRows &rownrs, const Array< VirtualType > &data)
Put some array values in the column.
virtual void putColumnSliceCells(const RefRows &rownrs, const Slicer &slicer, const Array< VirtualType > &data)
Put into a section of some arrays in the column.
BaseMappedArrayEngine()
The default constructor is required for reconstruction of the engine when a table is read back...
void getColumnSlice(const Slicer &slicer, Array< VirtualType > &array)
Get a section of all arrays in the column.
virtual void addRow64(rownr_t nrrow)
Rows are added to the end of the table.
virtual int dataType() const
Return the data type of the column.
virtual void mapOnPut(const Array< VirtualType > &array, Array< StoredType > &stored)
Map Bool array to bit flags array.
virtual void setShapeColumn(const IPosition &shape)
Set the shape of the FixedShape arrays in the column.
virtual void addRowInit(rownr_t startRow, rownr_t nrrow)
virtual IPosition shape(rownr_t rownr)
Get the shape of the (underlying) array in the given row.
virtual DataManagerColumn * makeIndArrColumn(const String &columnName, int dataType, const String &dataTypeId)
Create the column object for the array column in this engine.
ArrayColumn< StoredType > * column_p
virtual void putSlice(rownr_t rownr, const Slicer &slicer, const Array< VirtualType > &array)
Put into a section of the array in the given row.
virtual uInt ndim(rownr_t rownr)
Get the dimensionality of the (underlying) array in the given row.
const String & storedName() const
Get the stored column name.
void setWritable(Bool isWritable)
Set if the column is writable or not.
void prepare1()
Do the 2 stages of the prepare (define columns and adding rows).
virtual void create64(rownr_t initialNrrow)
Initialize the object for a new table.
virtual Slicer getStoredSlicer(const Slicer &virtualSlicer) const
Map the slicer for a virtual shape to a stored shape.
Class holding the row numbers in a RefTable.
Definition: RefRows.h:85
virtual void getSlice(rownr_t rownr, const Slicer &slicer, Array< VirtualType > &array)
Get a section of the array in the given row.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual void getArray(rownr_t rownr, Array< VirtualType > &array)
Get an array in the given row.
Read/write access to a table column.
Definition: TableColumn.h:98
A templated N-D Array class with zero origin. Array&lt;T, Alloc&gt; is a templated, N-dimensional, Array class. The origin is zero, but by default indices are zero-based. This Array class is the base class for the Vector, Matrix, and Cube subclasses.
Definition: Array.h:156
virtual void getArrayColumn(Array< VirtualType > &array)
Get an entire column.
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:288
virtual void putArrayColumn(const Array< VirtualType > &array)
Put an entire column.
virtual Bool isWritable() const
The column is writable if the underlying stored column is writable.
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46
virtual IPosition getStoredShape(rownr_t rownr, const IPosition &virtualShape)
Map the virtual shape to the stored shape.
virtual void putArray(rownr_t rownr, const Array< VirtualType > &array)
Put an array in the given row.
TableColumn makeTableColumn(const String &columnName)
Make a table column object for the given column.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual Bool isShapeDefined(rownr_t rownr)
Test if the (underlying) array is defined in the given row.
void putColumnSlice(const Slicer &slicer, const Array< VirtualType > &array)
Put a section of all arrays in the column.
~BaseMappedArrayEngine()
Destructor is mandatory.
unsigned int uInt
Definition: aipstype.h:51