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 getInt64V (uInt rownr, Int64* dataPtr);
148  void getfloatV (uInt rownr, float* dataPtr);
149  void getdoubleV (uInt rownr, double* dataPtr);
150  void getComplexV (uInt rownr, Complex* dataPtr);
151  void getDComplexV (uInt rownr, DComplex* dataPtr);
152  void getStringV (uInt rownr, String* dataPtr);
153  // </group>
154 
155  // Get the scalar value with a non-standard data type in the given row.
156  void getOtherV (uInt rownr, void* dataPtr);
157 
158  // Put the scalar value with a standard data type into the given row.
159  // This throws an exception, because putting is not supported.
160  // <group>
161  void putBoolV (uInt rownr, const Bool* dataPtr);
162  void putuCharV (uInt rownr, const uChar* dataPtr);
163  void putShortV (uInt rownr, const Short* dataPtr);
164  void putuShortV (uInt rownr, const uShort* dataPtr);
165  void putIntV (uInt rownr, const Int* dataPtr);
166  void putuIntV (uInt rownr, const uInt* dataPtr);
167  void putInt64V (uInt rownr, const Int64* dataPtr);
168  void putfloatV (uInt rownr, const float* dataPtr);
169  void putdoubleV (uInt rownr, const double* dataPtr);
170  void putComplexV (uInt rownr, const Complex* dataPtr);
171  void putDComplexV (uInt rownr, const DComplex* dataPtr);
172  void putStringV (uInt rownr, const String* dataPtr);
173  // </group>
174 
175  // Put the scalar value with a non-standard data type into the given row.
176  // This throws an exception, because putting is not supported.
177  void putOtherV (uInt rownr, const void* dataPtr);
178 
179  // Get the array value in the given row.
180  // The argument dataPtr is in fact a Array<T>*, but a void*
181  // is needed to be generic.
182  // The array pointed to by dataPtr has to have the correct shape
183  // (which is guaranteed by the ArrayColumn get function).
184  void getArrayV (uInt rownr, void* dataPtr);
185 
186  // Put the array value into the given row.
187  // This throws an exception, because putting is not supported.
188  void putArrayV (uInt rownr, const void* dataPtr);
189 
190  // Get a section of the array in the given row.
191  // The argument dataPtr is in fact a Array<T>*, but a void*
192  // is needed to be generic.
193  // The array pointed to by dataPtr has to have the correct shape
194  // (which is guaranteed by the ArrayColumn getSlice function).
195  void getSliceV (uInt rownr, const Slicer& slicer, void* dataPtr);
196 
197  // Put into a section of the array in the given row.
198  // This throws an exception, because putting is not supported.
199  void putSliceV (uInt rownr, const Slicer& slicer, const void* dataPtr);
200 
201  // Convert the rownr to the rownr in the underlying table.
202  uInt convertRownr (uInt rownr);
203 
204  //# Now define the data members.
205  ForwardColumnIndexedRowEngine* enginePtr_p; //# pointer to parent engine
206 };
207 
208 
209 
210 
211 // <summary>
212 // Virtual column engine forwarding to other columns/rows.
213 // </summary>
214 
215 // <reviewed reviewer="" date="" tests="">
216 // </reviewed>
217 
218 // <use visibility=export>
219 
220 // <prerequisite>
221 //# Classes you should understand before using this one.
222 // <li> VirtualColumnEngine
223 // </prerequisite>
224 
225 // <etymology>
226 // ForwardColumnIndexedRowEngine is a virtual column engine which
227 // forwards the gets and puts of columns to corresponding columns
228 // in another table. Furthermore it maps the row number by indexing
229 // the row number in the referenced table.
230 // </etymology>
231 
232 // <synopsis>
233 // ForwardColumnIndexedRowEngine is a data manager which forwards
234 // the gets and puts of columns to columns with the same names in
235 // another table. In that sense it is the same as the virtual column engine
236 // <linkto class="ForwardColumnEngine:description">
237 // ForwardColumnEngine</linkto>.
238 // However, it also forwards the row number. That is, it uses a column
239 // containing row numbers to index the correct row in the referenced table.
240 // The name of this column and the name of the referenced table have to
241 // be given when constructing the engine.
242 //
243 // For example:<br>
244 // Table TABA contains columns A, B and C and consists of N rows.
245 // Table TABF uses ForwardColumnIndexedRowEngine to forward its columns
246 // A, B and C to the corresponding columns in TABA. Furthermore it
247 // contains a column ROW containing row numbers in TABA. This column is
248 // the mapping of row numbers in TABF to rows in TABA. E.g. if ROW has
249 // the value 25 in row 10, row 10 of TABF is forwarded to row 25 in TABA.
250 //
251 // Actually, puts are not possible. When multiple rows map to the same row
252 // in the referenced table, putting a value in one row would also change
253 // the value in another row referencing the same underlying row. This
254 // could result in unexpected behaviour.
255 //
256 // The engine consists of a set of
257 // <linkto class="ForwardColumnIndexedRow:description">
258 // ForwardColumnIndexedRow</linkto>
259 // objects, which handle the actual gets.
260 // </synopsis>
261 
262 // <motivation>
263 // In some ways it overlaps the functionality of the storage manager
264 // StManMirAIO. They both allow to have the same value used by multiple
265 // rows. However, StManMirAIO only allows that for consecutive rows,
266 // while this engine allows it for any row. On the other side,
267 // StManMirAIO is faster.
268 // </motivation>
269 
270 // <example>
271 // <srcblock>
272 // // The original table.
273 // Table tab("someTable");
274 // // Create another table with the same description.
275 // SetupNewTable newtab("tForwardColRow.data", tab.tableDesc(), Table::New);
276 // // Create an engine which forwards to the original table and uses
277 // // column rowColumn to get the row number in the referenced table.
278 // // Bind all columns in the new table to the forwarding engine.
279 // ForwardColumnIndexedRowEngine fce(tab, "rowColumn");
280 // newtab.bindAll (fce);
281 // // Create the new table.
282 // // Every get and put on this table is forwarded to the original table.
283 // // NB. Puts cannot be done here, because the original table was
284 // // opened as readonly.
285 // // Of course, some columns could have been bound to another
286 // // data manager (storage manager, calibration engine, ...).
287 // Table forwTab(newtab);
288 // </srcblock>
289 // </example>
290 
292 {
293 public:
294 
295  // The default constructor is required for reconstruction of the
296  // engine when a table is read back.
297  ForwardColumnIndexedRowEngine (const String& dataManagerName,
298  const Record& spec);
299 
300  // Create the engine.
301  // The columns using this engine will reference the given table.
302  // The column with the given name contains the row number mapping,
303  // i.e. a row number in a get or put is converted to a row number
304  // in the referenced table using the value in this column.
305  // The data manager gets the given name.
306  ForwardColumnIndexedRowEngine (const Table& referencedTable,
307  const String& rowColumnName,
308  const String& dataManagerName);
309 
310  // Create the engine.
311  // The columns using this engine will reference the given table.
312  // The column with the given name contains the row number mapping,
313  // i.e. a row number in a get or put is converted to a row number
314  // in the referenced table using the value in this column.
315  // The data manager has no name.
316  ForwardColumnIndexedRowEngine (const Table& referencedTable,
317  const String& rowColumnName);
318 
319  // Destructor is mandatory.
321 
322  // Clone the engine object.
323  DataManager* clone() const;
324 
325  // Return the type name of the engine
326  // (i.e. its class name ForwardColumnIndexedRowEngine).
327  String dataManagerType() const;
328 
329  // Record a record containing data manager specifications.
330  virtual Record dataManagerSpec() const;
331 
332  // Return the name of the class.
333  static String className();
334 
335  // Register the class name and the static makeObject "constructor".
336  // This will make the engine known to the table system.
337  static void registerClass();
338 
339 private:
340  // The copy constructor is forbidden (so it is private).
342 
343  // Assignment is forbidden (so it is private).
346 
347  // Create the column object for the scalar column in this engine.
348  DataManagerColumn* makeScalarColumn (const String& columnName,
349  int dataType,
350  const String& dataTypeId);
351 
352  // Create the column object for the indirect array column in this engine.
353  DataManagerColumn* makeIndArrColumn (const String& columnName,
354  int dataType,
355  const String& dataTypeId);
356 
357  // Initialize the object for a new table.
358  // It defines the column keywords containing the name of the
359  // original table, which can be the parent of the referenced table.
360  // It also defines a keyword containing the row column name.
361  void create (uInt initialNrrow);
362 
363  // Initialize the engine.
364  // It gets the name of the original table(s) from the column keywords,
365  // opens those tables and attaches the ForwardColumnIndexedRow objects
366  // to the columns in those tables.
367  void prepare();
368 
369  // Reopen the engine for read/write access.
370  // This cannot be done, so all columns remain readonly.
371  // The function is needed to override the behaviour of its base class.
372  void reopenRW();
373 
374 
375  // Define the column with the row numbers (must have data type uInt).
378  // Define the various engine column objects.
380  // Cache of last row used to get row number.
383 
384 
385 public:
386  // Define the "constructor" to construct this engine when a
387  // table is read back.
388  // This "constructor" has to be registered by the user of the engine.
389  // If the engine is commonly used, its registration can be added
390  // into the registerAllCtor function in DataManReg.cc.
391  // This function gets automatically invoked by the table system.
392  static DataManager* makeObject (const String& dataManagerName,
393  const Record& spec);
394 
395  // Convert the rownr to the rownr in the underlying table.
396  uInt convertRownr (uInt rownr);
397 };
398 
399 
401 {
402  if (Int(rownr) != lastRow_p) {
403  rowNumber_p = rowColumn_p(rownr);
404  lastRow_p = rownr;
405  }
406  return rowNumber_p;
407 }
408 
410  { return enginePtr_p->convertRownr (rownr); }
411 
412 
413 
414 } //# NAMESPACE CASACORE - END
415 
416 #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.
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
void getComplexV(uInt rownr, Complex *dataPtr)
int Int
Definition: aipstype.h:50
Main interface class to a read/write table.
Definition: Table.h:153
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:611
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:1003
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:416
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:814
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
void putInt64V(uInt rownr, const Int64 *dataPtr)
Abstract base class for a data manager.
Definition: DataManager.h:224
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
void getInt64V(uInt rownr, Int64 *dataPtr)
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