casa  5.7.0-16
 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 (uInt rownr, Array<T>& data);
130 // </src>
131 // <dt><src>
132 // void putArray (uInt 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 (uInt rownr, const Slicer& slicer, Array<T>& data);
142 // </src>
143 // <dt><src>
144 // void putSlice (uInt 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 (uInt rownr, const IPosition& shape);
169 // </src>
170 // <dt><src>
171 // uInt ndim (uInt rownr);
172 // </src>
173 // <dt><src>
174 // IPosition shape (uInt 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 create (uInt nrrow);
188 // </src>
189 // <dt><src>
190 // void open (uInt 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 addRow (uInt nrrow);
211 // </src>
212 // <dt><src>
213 // void removeRow (uInt 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 (uInt 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 create (uInt 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 addRow (uInt nrrow);
348  virtual void addRowInit (uInt startRow, uInt 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 (uInt rownr, const IPosition& shape);
364 
365  // Test if the (underlying) array is defined in the given row.
366  virtual Bool isShapeDefined (uInt 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 (uInt 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 (uInt 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 (uInt 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 (uInt 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 (uInt 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 (uInt 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,
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 (uInt 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  uInt 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:119
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.
virtual void putSlice(uInt rownr, const Slicer &slicer, const Array< VirtualType > &array)
Put into a section of the array in the given row.
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.
virtual void putArray(uInt rownr, const Array< VirtualType > &array)
Put an array in the given row.
ArrayColumn< StoredType > & column()
Give access to the stored column.
const String & columnName() const
Get rhe column name.
Definition: DataManager.h:1003
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.
Definition: DataManager.h:611
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition: ExprNode.h:1886
Templated base class for virtual array column.
Definition: VirtArrCol.h:140
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 void addRow(uInt nrrow)
Rows are added to the end of the table.
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 getArray(uInt rownr, Array< VirtualType > &array)
Get an array in the given row.
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(uInt startRow, uInt nrrow)
virtual DataManagerColumn * makeIndArrColumn(const String &columnName, int dataType, const String &dataTypeId)
Create the column object for the array column in this engine.
ABSTRACT CLASSES Deliberately vague to be general enough to allow for many different types of data
Definition: PlotData.h:48
ArrayColumn< StoredType > * column_p
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 IPosition shape(uInt rownr)
Get the shape of the (underlying) array in the given row.
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 Bool isShapeDefined(uInt rownr)
Test if the (underlying) array is defined in the given row.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
Read/write access to a table column.
Definition: TableColumn.h:98
template &lt;class T, class U&gt; class vector;
Definition: MSFlagger.h:37
virtual void getArrayColumn(Array< VirtualType > &array)
Get an entire column.
virtual void create(uInt initialNrrow)
Initialize the object for a new table.
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
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.
TableColumn makeTableColumn(const String &columnName)
Make a table column object for the given column.
virtual IPosition getStoredShape(uInt rownr, const IPosition &virtualShape)
Map the virtual shape to the stored shape.
virtual void getSlice(uInt rownr, const Slicer &slicer, Array< VirtualType > &array)
Get a section of the array in the given row.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
virtual void setShape(uInt rownr, const IPosition &shape)
Define the shape of the array 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.
virtual uInt ndim(uInt rownr)
Get the dimensionality of the (underlying) array in the given row.
unsigned int uInt
Definition: aipstype.h:51
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42