casacore
ForwardColRow.h
Go to the documentation of this file.
1 //# ForwardColRow.h: Virtual Column Engine to forward to other rows/columns
2 //# Copyright (C) 1995,1996,1997,2001
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_FORWARDCOLROW_H
29 #define TABLES_FORWARDCOLROW_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/DataMan/ForwardCol.h>
34 #include <casacore/tables/Tables/ScalarColumn.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class ForwardColumnIndexedRowEngine;
40 
41 
42 // <summary>
43 // Virtual column forwarding to another row/column
44 // </summary>
45 
46 // <reviewed reviewer="Paul Shannon" date="1995/05/22" tests="tForwardColRow.cc">
47 // </reviewed>
48 
49 // <use visibility=local>
50 
51 // <prerequisite>
52 //# Classes you should understand before using this one.
53 // <li> ForwardColumnIndexedRowEngine
54 // <li> ForwardColumn
55 // </prerequisite>
56 
57 // <etymology>
58 // ForwardColumnIndexedRow handles the forwarding of the gets and puts
59 // for an individual row/column on behalf of the virtual column engine
60 // ForwardColumnIndexedRowEngine. It forwards them to a row/column in
61 // another table. The row forwarding is done using a special column
62 // containing row numbers indexing the referenced table.
63 // </etymology>
64 
65 // <synopsis>
66 // ForwardColumnIndexedRow represents a virtual column which forwards the
67 // gets and puts to a column with the same name in another table.
68 // It is, in fact, a reference to the other column.
69 // The row numbers in the column are mapped to row numbers in the referenced
70 // column using a special column containing the mapping.
71 // The name of the other table is stored as a keyword in the
72 // forwarding column. When the referenced column is in its turn a
73 // ForwardColumn (note: not a ForwardColumnIndexedRow), the table
74 // mentioned in there will be used. In this way, the length of the
75 // forwarding chain is kept to a minimum.
76 //
77 // An object of this class is created (and deleted) by the virtual column
78 // engine
79 // <linkto class="ForwardColumnIndexedRowEngine:description">
80 // ForwardColumnIndexedRowEngine</linkto>
81 // which creates a ForwardColumnIndexedRow object for each column being
82 // forwarded.
83 // </synopsis>
84 
85 
87 {
88 public:
89 
90  // Construct it for the given column.
92  const String& columnName,
93  int dataType,
94  const String& dataTypeId,
95  const Table& referencedTable);
96 
97  // Destructor is mandatory.
99 
100  // Initialize the object.
101  // This means binding the column to the column with the same name
102  // in the original table.
103  // It checks if the description of both columns is the same.
104  void prepare (const Table& thisTable);
105 
106 private:
107  // Copy constructor is not needed and therefore forbidden
108  // (so make it private).
110 
111  // Assignment is not needed and therefore forbidden (so make it private).
113 
114  // This data manager cannot handle changing array shapes.
115  Bool canChangeShape() const;
116 
117  // This data manager cannot do get/putColumn.
118  Bool canAccessScalarColumn (Bool& reask) const;
119 
120  // This data manager cannot do get/putColumn.
121  Bool canAccessArrayColumn (Bool& reask) const;
122 
123  // This data manager cannot do get/putColumn.
124  Bool canAccessColumnSlice (Bool& reask) const;
125 
126  // Set the shape of an (indirect) array in the given row.
127  // This throws an exception, because putting is not supported.
128  void setShape (uInt rownr, const IPosition& shape);
129 
130  // Is the value shape defined in the given row?
131  Bool isShapeDefined (uInt rownr);
132 
133  // Get the dimensionality of the item in the given row.
134  uInt ndim (uInt rownr);
135 
136  // Get the shape of the item in the given row.
137  IPosition shape (uInt rownr);
138 
139  // Get the scalar value with a standard data type in the given row.
140  // <group>
141  void getBoolV (uInt rownr, Bool* dataPtr);
142  void getuCharV (uInt rownr, uChar* dataPtr);
143  void getShortV (uInt rownr, Short* dataPtr);
144  void getuShortV (uInt rownr, uShort* dataPtr);
145  void getIntV (uInt rownr, Int* dataPtr);
146  void getuIntV (uInt rownr, uInt* dataPtr);
147  void getfloatV (uInt rownr, float* dataPtr);
148  void getdoubleV (uInt rownr, double* dataPtr);
149  void getComplexV (uInt rownr, Complex* dataPtr);
150  void getDComplexV (uInt rownr, DComplex* dataPtr);
151  void getStringV (uInt rownr, String* dataPtr);
152  // </group>
153 
154  // Get the scalar value with a non-standard data type in the given row.
155  void getOtherV (uInt rownr, void* dataPtr);
156 
157  // Put the scalar value with a standard data type into the given row.
158  // This throws an exception, because putting is not supported.
159  // <group>
160  void putBoolV (uInt rownr, const Bool* dataPtr);
161  void putuCharV (uInt rownr, const uChar* dataPtr);
162  void putShortV (uInt rownr, const Short* dataPtr);
163  void putuShortV (uInt rownr, const uShort* dataPtr);
164  void putIntV (uInt rownr, const Int* dataPtr);
165  void putuIntV (uInt rownr, const uInt* dataPtr);
166  void putfloatV (uInt rownr, const float* dataPtr);
167  void putdoubleV (uInt rownr, const double* dataPtr);
168  void putComplexV (uInt rownr, const Complex* dataPtr);
169  void putDComplexV (uInt rownr, const DComplex* dataPtr);
170  void putStringV (uInt rownr, const String* dataPtr);
171  // </group>
172 
173  // Put the scalar value with a non-standard data type into the given row.
174  // This throws an exception, because putting is not supported.
175  void putOtherV (uInt rownr, const void* dataPtr);
176 
177  // Get the array value in the given row.
178  // The argument dataPtr is in fact a Array<T>*, but a void*
179  // is needed to be generic.
180  // The array pointed to by dataPtr has to have the correct shape
181  // (which is guaranteed by the ArrayColumn get function).
182  void getArrayV (uInt rownr, void* dataPtr);
183 
184  // Put the array value into the given row.
185  // This throws an exception, because putting is not supported.
186  void putArrayV (uInt rownr, const void* dataPtr);
187 
188  // Get a section of the array in the given row.
189  // The argument dataPtr is in fact a Array<T>*, but a void*
190  // is needed to be generic.
191  // The array pointed to by dataPtr has to have the correct shape
192  // (which is guaranteed by the ArrayColumn getSlice function).
193  void getSliceV (uInt rownr, const Slicer& slicer, void* dataPtr);
194 
195  // Put into a section of the array in the given row.
196  // This throws an exception, because putting is not supported.
197  void putSliceV (uInt rownr, const Slicer& slicer, const void* dataPtr);
198 
199  // Convert the rownr to the rownr in the underlying table.
200  uInt convertRownr (uInt rownr);
201 
202  //# Now define the data members.
203  ForwardColumnIndexedRowEngine* enginePtr_p; //# pointer to parent engine
204 };
205 
206 
207 
208 
209 // <summary>
210 // Virtual column engine forwarding to other columns/rows.
211 // </summary>
212 
213 // <reviewed reviewer="" date="" tests="">
214 // </reviewed>
215 
216 // <use visibility=export>
217 
218 // <prerequisite>
219 //# Classes you should understand before using this one.
220 // <li> VirtualColumnEngine
221 // </prerequisite>
222 
223 // <etymology>
224 // ForwardColumnIndexedRowEngine is a virtual column engine which
225 // forwards the gets and puts of columns to corresponding columns
226 // in another table. Furthermore it maps the row number by indexing
227 // the row number in the referenced table.
228 // </etymology>
229 
230 // <synopsis>
231 // ForwardColumnIndexedRowEngine is a data manager which forwards
232 // the gets and puts of columns to columns with the same names in
233 // another table. In that sense it is the same as the virtual column engine
234 // <linkto class="ForwardColumnEngine:description">
235 // ForwardColumnEngine</linkto>.
236 // However, it also forwards the row number. That is, it uses a column
237 // containing row numbers to index the correct row in the referenced table.
238 // The name of this column and the name of the referenced table have to
239 // be given when constructing the engine.
240 //
241 // For example:<br>
242 // Table TABA contains columns A, B and C and consists of N rows.
243 // Table TABF uses ForwardColumnIndexedRowEngine to forward its columns
244 // A, B and C to the corresponding columns in TABA. Furthermore it
245 // contains a column ROW containing row numbers in TABA. This column is
246 // the mapping of row numbers in TABF to rows in TABA. E.g. if ROW has
247 // the value 25 in row 10, row 10 of TABF is forwarded to row 25 in TABA.
248 //
249 // Actually, puts are not possible. When multiple rows map to the same row
250 // in the referenced table, putting a value in one row would also change
251 // the value in another row referencing the same underlying row. This
252 // could result in unexpected behaviour.
253 //
254 // The engine consists of a set of
255 // <linkto class="ForwardColumnIndexedRow:description">
256 // ForwardColumnIndexedRow</linkto>
257 // objects, which handle the actual gets.
258 // </synopsis>
259 
260 // <motivation>
261 // In some ways it overlaps the functionality of the storage manager
262 // StManMirAIO. They both allow to have the same value used by multiple
263 // rows. However, StManMirAIO only allows that for consecutive rows,
264 // while this engine allows it for any row. On the other side,
265 // StManMirAIO is faster.
266 // </motivation>
267 
268 // <example>
269 // <srcblock>
270 // // The original table.
271 // Table tab("someTable");
272 // // Create another table with the same description.
273 // SetupNewTable newtab("tForwardColRow.data", tab.tableDesc(), Table::New);
274 // // Create an engine which forwards to the original table and uses
275 // // column rowColumn to get the row number in the referenced table.
276 // // Bind all columns in the new table to the forwarding engine.
277 // ForwardColumnIndexedRowEngine fce(tab, "rowColumn");
278 // newtab.bindAll (fce);
279 // // Create the new table.
280 // // Every get and put on this table is forwarded to the original table.
281 // // NB. Puts cannot be done here, because the original table was
282 // // opened as readonly.
283 // // Of course, some columns could have been bound to another
284 // // data manager (storage manager, calibration engine, ...).
285 // Table forwTab(newtab);
286 // </srcblock>
287 // </example>
288 
290 {
291 public:
292 
293  // The default constructor is required for reconstruction of the
294  // engine when a table is read back.
295  ForwardColumnIndexedRowEngine (const String& dataManagerName,
296  const Record& spec);
297 
298  // Create the engine.
299  // The columns using this engine will reference the given table.
300  // The column with the given name contains the row number mapping,
301  // i.e. a row number in a get or put is converted to a row number
302  // in the referenced table using the value in this column.
303  // The data manager gets the given name.
304  ForwardColumnIndexedRowEngine (const Table& referencedTable,
305  const String& rowColumnName,
306  const String& dataManagerName);
307 
308  // Create the engine.
309  // The columns using this engine will reference the given table.
310  // The column with the given name contains the row number mapping,
311  // i.e. a row number in a get or put is converted to a row number
312  // in the referenced table using the value in this column.
313  // The data manager has no name.
314  ForwardColumnIndexedRowEngine (const Table& referencedTable,
315  const String& rowColumnName);
316 
317  // Destructor is mandatory.
319 
320  // Clone the engine object.
321  DataManager* clone() const;
322 
323  // Return the type name of the engine
324  // (i.e. its class name ForwardColumnIndexedRowEngine).
325  String dataManagerType() const;
326 
327  // Record a record containing data manager specifications.
328  virtual Record dataManagerSpec() const;
329 
330  // Return the name of the class.
331  static String className();
332 
333  // Register the class name and the static makeObject "constructor".
334  // This will make the engine known to the table system.
335  static void registerClass();
336 
337 private:
338  // The copy constructor is forbidden (so it is private).
340 
341  // Assignment is forbidden (so it is private).
344 
345  // Create the column object for the scalar column in this engine.
346  DataManagerColumn* makeScalarColumn (const String& columnName,
347  int dataType,
348  const String& dataTypeId);
349 
350  // Create the column object for the indirect array column in this engine.
351  DataManagerColumn* makeIndArrColumn (const String& columnName,
352  int dataType,
353  const String& dataTypeId);
354 
355  // Initialize the object for a new table.
356  // It defines the column keywords containing the name of the
357  // original table, which can be the parent of the referenced table.
358  // It also defines a keyword containing the row column name.
359  void create (uInt initialNrrow);
360 
361  // Initialize the engine.
362  // It gets the name of the original table(s) from the column keywords,
363  // opens those tables and attaches the ForwardColumnIndexedRow objects
364  // to the columns in those tables.
365  void prepare();
366 
367  // Reopen the engine for read/write access.
368  // This cannot be done, so all columns remain readonly.
369  // The function is needed to override the behaviour of its base class.
370  void reopenRW();
371 
372 
373  // Define the column with the row numbers (must have data type uInt).
376  // Define the various engine column objects.
378  // Cache of last row used to get row number.
381 
382 
383 public:
384  // Define the "constructor" to construct this engine when a
385  // table is read back.
386  // This "constructor" has to be registered by the user of the engine.
387  // If the engine is commonly used, its registration can be added
388  // into the registerAllCtor function in DataManReg.cc.
389  // This function gets automatically invoked by the table system.
390  static DataManager* makeObject (const String& dataManagerName,
391  const Record& spec);
392 
393  // Convert the rownr to the rownr in the underlying table.
394  uInt convertRownr (uInt rownr);
395 };
396 
397 
399 {
400  if (Int(rownr) != lastRow_p) {
401  rowNumber_p = rowColumn_p(rownr);
402  lastRow_p = rownr;
403  }
404  return rowNumber_p;
405 }
406 
408  { return enginePtr_p->convertRownr (rownr); }
409 
410 
411 
412 } //# NAMESPACE CASACORE - END
413 
414 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
void putComplexV(uInt rownr, const Complex *dataPtr)
Int lastRow_p
Cache of last row used to get row number.
Bool canAccessArrayColumn(Bool &reask) const
This data manager cannot do get/putColumn.
void getComplexV(uInt rownr, Complex *dataPtr)
int Int
Definition: aipstype.h:50
Main interface class to a read/write table.
Definition: Table.h:149
IPosition shape(uInt rownr)
Get the shape of the item in the given row.
void setShape(uInt rownr, const IPosition &shape)
Set the shape of an (indirect) array in the given row.
Abstract base class for a column in a data manager.
Definition: DataManager.h:619
PtrBlock< ForwardColumnIndexedRow * > refColumns_p
Define the various engine column objects.
unsigned char uChar
Definition: aipstype.h:47
Bool canChangeShape() const
This data manager cannot handle changing array shapes.
const String & columnName() const
Get rhe column name.
Definition: DataManager.h:1007
void putuCharV(uInt rownr, const uChar *dataPtr)
void putShortV(uInt rownr, const Short *dataPtr)
void putStringV(uInt rownr, const String *dataPtr)
void putuIntV(uInt rownr, const uInt *dataPtr)
uInt convertRownr(uInt rownr)
Convert the rownr to the rownr in the underlying table.
int dataType() const
Get the data type of the column as defined in DataType.h.
void getuShortV(uInt rownr, uShort *dataPtr)
Virtual column engine forwarding to other columns.
Definition: ForwardCol.h:414
Bool isShapeDefined(uInt rownr)
Is the value shape defined in the given row?
void getSliceV(uInt rownr, const Slicer &slicer, void *dataPtr)
Get a section of the array in the given row.
uInt convertRownr(uInt rownr)
Convert the rownr to the rownr in the underlying table.
short Short
Definition: aipstype.h:48
void getuIntV(uInt rownr, uInt *dataPtr)
void putIntV(uInt rownr, const Int *dataPtr)
Bool canAccessScalarColumn(Bool &reask) const
This data manager cannot do get/putColumn.
uInt ndim(uInt rownr)
Get the dimensionality of the item in the given row.
void getDComplexV(uInt rownr, DComplex *dataPtr)
void getArrayV(uInt rownr, void *dataPtr)
Get the array value in the given row.
void getShortV(uInt rownr, Short *dataPtr)
void getIntV(uInt rownr, Int *dataPtr)
ForwardColumnIndexedRow(ForwardColumnIndexedRowEngine *enginePtr, const String &columnName, int dataType, const String &dataTypeId, const Table &referencedTable)
Construct it for the given column.
void putOtherV(uInt rownr, const void *dataPtr)
Put the scalar value with a non-standard data type into the given row.
ForwardColumnIndexedRow & operator=(const ForwardColumnIndexedRow &)
Assignment is not needed and therefore forbidden (so make it private).
void putDComplexV(uInt rownr, const DComplex *dataPtr)
void getdoubleV(uInt rownr, double *dataPtr)
void putfloatV(uInt rownr, const float *dataPtr)
void getOtherV(uInt rownr, void *dataPtr)
Get the scalar value with a non-standard data type in the given row.
Virtual column forwarding to another column.
Definition: ForwardCol.h:91
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
String dataTypeId() const
Get the data type id of the column for dataType==TpOther.
void putSliceV(uInt rownr, const Slicer &slicer, const void *dataPtr)
Put into a section of the array in the given row.
void putBoolV(uInt rownr, const Bool *dataPtr)
Put the scalar value with a standard data type into the given row.
ForwardColumnIndexedRowEngine * enginePtr_p
void putdoubleV(uInt rownr, const double *dataPtr)
void getBoolV(uInt rownr, Bool *dataPtr)
Get the scalar value with a standard data type in the given row.
~ForwardColumnIndexedRow()
Destructor is mandatory.
String rowColumnName_p
Define the column with the row numbers (must have data type uInt).
void getfloatV(uInt rownr, float *dataPtr)
A drop-in replacement for Block<T*>.
Definition: Block.h:861
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
Abstract base class for a data manager.
Definition: DataManager.h:222
void getuCharV(uInt rownr, uChar *dataPtr)
Virtual column engine forwarding to other columns/rows.
void prepare(const Table &thisTable)
Initialize the object.
Bool canAccessColumnSlice(Bool &reask) const
This data manager cannot do get/putColumn.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
void putuShortV(uInt rownr, const uShort *dataPtr)
void putArrayV(uInt rownr, const void *dataPtr)
Put the array value into the given row.
Virtual column forwarding to another row/column.
Definition: ForwardColRow.h:86
this file contains all the compiler specific defines
Definition: mainpage.dox:28
void getStringV(uInt rownr, String *dataPtr)
unsigned int uInt
Definition: aipstype.h:51
unsigned short uShort
Definition: aipstype.h:49