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