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: 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>
33#include <casacore/tables/DataMan/VirtColEng.h>
34#include <casacore/tables/DataMan/VirtArrCol.h>
35#include <casacore/casa/Arrays/IPosition.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40template<class T> class ArrayColumn;
41class 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
265template<class VirtualType, class StoredType> class BaseMappedArrayEngine : public VirtualColumnEngine, public VirtualArrayColumn<VirtualType>
266{
267public:
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
277protected:
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.
302
303 // Set the virtual and stored column name.
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.
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,
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,
405
406 // Get an entire column.
407 // This will scale and offset from the underlying array.
409
410 // Put an entire column.
411 // This will scale and offset to the underlying 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.
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.
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.
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
466private:
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
488template<class VirtualType, class StoredType>
489inline const String&
492
493template<class VirtualType, class StoredType>
494inline const String&
497
498template<class VirtualType, class StoredType>
499inline void
501 (const String& virtualName, const String& storedName)
502{
503 virtualName_p = virtualName;
504 storedName_p = storedName;
505}
506
507template<class VirtualType, class StoredType>
508inline void
510 { isWritable_p = isWritable; }
511
512template<class VirtualType, class StoredType>
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
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.
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 BaseMappedArrayEngine< VirtualType, StoredType > &)
Copy constructor is only used by copy constructor of derived classes.
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:225
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:51
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
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:46