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.
void getComplexV(uInt rownr, Complex *dataPtr)
int Int
Definition: aipstype.h:47
Main interface class to a read/write table.
Definition: Table.h:149
const String & columnName() const
Get rhe column name.
Definition: DataManager.h:1000
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:616
PtrBlock< ForwardColumnIndexedRow * > refColumns_p
Define the various engine column objects.
Bool canAccessColumnSlice(Bool &reask) const
This data manager cannot do get/putColumn.
unsigned char uChar
Definition: aipstype.h:44
void putuCharV(uInt rownr, const uChar *dataPtr)
void putShortV(uInt rownr, const Short *dataPtr)
String dataTypeId() const
Get the data type id of the column for dataType==TpOther.
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.
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:45
void getuIntV(uInt rownr, uInt *dataPtr)
void putIntV(uInt rownr, const Int *dataPtr)
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:181
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
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)
Bool canChangeShape() const
This data manager cannot handle changing array shapes.
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:275
Abstract base class for a data manager.
Definition: DataManager.h:222
Bool canAccessArrayColumn(Bool &reask) const
This data manager cannot do get/putColumn.
void getuCharV(uInt rownr, uChar *dataPtr)
Virtual column engine forwarding to other columns/rows.
void prepare(const Table &thisTable)
Initialize the object.
Bool canAccessScalarColumn(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
int dataType() const
Get the data type of the column as defined in DataType.h.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
void getStringV(uInt rownr, String *dataPtr)
unsigned int uInt
Definition: aipstype.h:48
unsigned short uShort
Definition: aipstype.h:46