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.
116 
117  // Set the shape of an (indirect) array in the given row.
118  // This throws an exception, because putting is not supported.
119  void setShape (rownr_t rownr, const IPosition& shape);
120 
121  // Is the value shape defined in the given row?
123 
124  // Get the dimensionality of the item in the given row.
125  uInt ndim (rownr_t rownr);
126 
127  // Get the shape of the item in the given row.
129 
130  // Get the scalar value with a standard data type in the given row.
131  // <group>
132  virtual void getBool (rownr_t rownr, Bool* dataPtr);
133  virtual void getuChar (rownr_t rownr, uChar* dataPtr);
134  virtual void getShort (rownr_t rownr, Short* dataPtr);
135  virtual void getuShort (rownr_t rownr, uShort* dataPtr);
136  virtual void getInt (rownr_t rownr, Int* dataPtr);
137  virtual void getuInt (rownr_t rownr, uInt* dataPtr);
138  virtual void getInt64 (rownr_t rownr, Int64* dataPtr);
139  virtual void getfloat (rownr_t rownr, float* dataPtr);
140  virtual void getdouble (rownr_t rownr, double* dataPtr);
141  virtual void getComplex (rownr_t rownr, Complex* dataPtr);
142  virtual void getDComplex (rownr_t rownr, DComplex* dataPtr);
143  virtual void getString (rownr_t rownr, String* dataPtr);
144  // </group>
145 
146  // Get the scalar value with a non-standard data type in the given row.
147  virtual void getOther (rownr_t rownr, void* dataPtr);
148 
149  // Put the scalar value with a standard data type into the given row.
150  // This throws an exception, because putting is not supported.
151  // <group>
152  virtual void putBool (rownr_t rownr, const Bool* dataPtr);
153  virtual void putuChar (rownr_t rownr, const uChar* dataPtr);
154  virtual void putShort (rownr_t rownr, const Short* dataPtr);
155  virtual void putuShort (rownr_t rownr, const uShort* dataPtr);
156  virtual void putInt (rownr_t rownr, const Int* dataPtr);
157  virtual void putuInt (rownr_t rownr, const uInt* dataPtr);
158  virtual void putInt64 (rownr_t rownr, const Int64* dataPtr);
159  virtual void putfloat (rownr_t rownr, const float* dataPtr);
160  virtual void putdouble (rownr_t rownr, const double* dataPtr);
161  virtual void putComplex (rownr_t rownr, const Complex* dataPtr);
162  virtual void putDComplex (rownr_t rownr, const DComplex* dataPtr);
163  virtual void putString (rownr_t rownr, const String* dataPtr);
164  // </group>
165 
166  // Put the scalar value with a non-standard data type into the given row.
167  // This throws an exception, because putting is not supported.
168  virtual void putOther (rownr_t rownr, const void* dataPtr);
169 
170  // Get the array value in the given row.
171  // The argument dataPtr is in fact a Array<T>&, but a ArrayBase&
172  // is needed to be generic.
173  // The array pointed to by dataPtr has to have the correct shape
174  // (which is guaranteed by the ArrayColumn get function).
175  void getArrayV (rownr_t rownr, ArrayBase& dataPtr);
176 
177  // Put the array value into the given row.
178  // This throws an exception, because putting is not supported.
179  void putArrayV (rownr_t rownr, const ArrayBase& dataPtr);
180 
181  // Get a section of the array in the given row.
182  // The argument dataPtr is in fact a Array<T>&, but a ArrayBase&
183  // is needed to be generic.
184  // The array pointed to by dataPtr has to have the correct shape
185  // (which is guaranteed by the ArrayColumn getSlice function).
186  void getSliceV (rownr_t rownr, const Slicer& slicer, ArrayBase& dataPtr);
187 
188  // Put into a section of the array in the given row.
189  // This throws an exception, because putting is not supported.
190  void putSliceV (rownr_t rownr, const Slicer& slicer, const ArrayBase& dataPtr);
191 
192  // Convert the rownr to the rownr in the underlying table.
193  rownr_t convertRownr (rownr_t rownr);
194 
195  //# Now define the data members.
196  ForwardColumnIndexedRowEngine* enginePtr_p; //# pointer to parent engine
197 };
198 
199 
200 
201 
202 // <summary>
203 // Virtual column engine forwarding to other columns/rows.
204 // </summary>
205 
206 // <reviewed reviewer="" date="" tests="">
207 // </reviewed>
208 
209 // <use visibility=export>
210 
211 // <prerequisite>
212 //# Classes you should understand before using this one.
213 // <li> VirtualColumnEngine
214 // </prerequisite>
215 
216 // <etymology>
217 // ForwardColumnIndexedRowEngine is a virtual column engine which
218 // forwards the gets and puts of columns to corresponding columns
219 // in another table. Furthermore it maps the row number by indexing
220 // the row number in the referenced table.
221 // </etymology>
222 
223 // <synopsis>
224 // ForwardColumnIndexedRowEngine is a data manager which forwards
225 // the gets and puts of columns to columns with the same names in
226 // another table. In that sense it is the same as the virtual column engine
227 // <linkto class="ForwardColumnEngine:description">
228 // ForwardColumnEngine</linkto>.
229 // However, it also forwards the row number. That is, it uses a column
230 // containing row numbers to index the correct row in the referenced table.
231 // The name of this column and the name of the referenced table have to
232 // be given when constructing the engine.
233 //
234 // For example:<br>
235 // Table TABA contains columns A, B and C and consists of N rows.
236 // Table TABF uses ForwardColumnIndexedRowEngine to forward its columns
237 // A, B and C to the corresponding columns in TABA. Furthermore it
238 // contains a column ROW containing row numbers in TABA. This column is
239 // the mapping of row numbers in TABF to rows in TABA. E.g. if ROW has
240 // the value 25 in row 10, row 10 of TABF is forwarded to row 25 in TABA.
241 //
242 // Actually, puts are not possible. When multiple rows map to the same row
243 // in the referenced table, putting a value in one row would also change
244 // the value in another row referencing the same underlying row. This
245 // could result in unexpected behaviour.
246 //
247 // The engine consists of a set of
248 // <linkto class="ForwardColumnIndexedRow:description">
249 // ForwardColumnIndexedRow</linkto>
250 // objects, which handle the actual gets.
251 // </synopsis>
252 
253 // <motivation>
254 // In some ways it overlaps the functionality of the storage manager
255 // StManMirAIO. They both allow to have the same value used by multiple
256 // rows. However, StManMirAIO only allows that for consecutive rows,
257 // while this engine allows it for any row. On the other side,
258 // StManMirAIO is faster.
259 // </motivation>
260 
261 // <example>
262 // <srcblock>
263 // // The original table.
264 // Table tab("someTable");
265 // // Create another table with the same description.
266 // SetupNewTable newtab("tForwardColRow.data", tab.tableDesc(), Table::New);
267 // // Create an engine which forwards to the original table and uses
268 // // column rowColumn to get the row number in the referenced table.
269 // // Bind all columns in the new table to the forwarding engine.
270 // ForwardColumnIndexedRowEngine fce(tab, "rowColumn");
271 // newtab.bindAll (fce);
272 // // Create the new table.
273 // // Every get and put on this table is forwarded to the original table.
274 // // NB. Puts cannot be done here, because the original table was
275 // // opened as readonly.
276 // // Of course, some columns could have been bound to another
277 // // data manager (storage manager, calibration engine, ...).
278 // Table forwTab(newtab);
279 // </srcblock>
280 // </example>
281 
283 {
284 public:
285 
286  // The default constructor is required for reconstruction of the
287  // engine when a table is read back.
289  const Record& spec);
290 
291  // Create the engine.
292  // The columns using this engine will reference the given table.
293  // The column with the given name contains the row number mapping,
294  // i.e. a row number in a get or put is converted to a row number
295  // in the referenced table using the value in this column.
296  // The data manager gets the given name.
297  ForwardColumnIndexedRowEngine (const Table& referencedTable,
298  const String& rowColumnName,
299  const String& dataManagerName);
300 
301  // Create the engine.
302  // The columns using this engine will reference the given table.
303  // The column with the given name contains the row number mapping,
304  // i.e. a row number in a get or put is converted to a row number
305  // in the referenced table using the value in this column.
306  // The data manager has no name.
307  ForwardColumnIndexedRowEngine (const Table& referencedTable,
308  const String& rowColumnName);
309 
310  // Destructor is mandatory.
312 
313  // Clone the engine object.
314  DataManager* clone() const;
315 
316  // Return the type name of the engine
317  // (i.e. its class name ForwardColumnIndexedRowEngine).
319 
320  // Record a record containing data manager specifications.
321  virtual Record dataManagerSpec() const;
322 
323  // Return the name of the class.
324  static String className();
325 
326  // Register the class name and the static makeObject "constructor".
327  // This will make the engine known to the table system.
328  static void registerClass();
329 
330 private:
331  // The copy constructor is forbidden (so it is private).
333 
334  // Assignment is forbidden (so it is private).
337 
338  // Create the column object for the scalar column in this engine.
340  int dataType,
341  const String& dataTypeId);
342 
343  // Create the column object for the indirect array column in this engine.
345  int dataType,
346  const String& dataTypeId);
347 
348  // Initialize the object for a new table.
349  // It defines the column keywords containing the name of the
350  // original table, which can be the parent of the referenced table.
351  // It also defines a keyword containing the row column name.
352  void create64 (rownr_t initialNrrow);
353 
354  // Initialize the engine.
355  // It gets the name of the original table(s) from the column keywords,
356  // opens those tables and attaches the ForwardColumnIndexedRow objects
357  // to the columns in those tables.
358  void prepare();
359 
360  // Reopen the engine for read/write access.
361  // This cannot be done, so all columns remain readonly.
362  // The function is needed to override the behaviour of its base class.
363  void reopenRW();
364 
365 
366  // Define the column with the row numbers (must have data type uInt).
369  // Define the various engine column objects.
371  // Cache of last row used to get row number.
374 
375 
376 public:
377  // Define the "constructor" to construct this engine when a
378  // table is read back.
379  // This "constructor" has to be registered by the user of the engine.
380  // If the engine is commonly used, its registration can be added
381  // into the registerAllCtor function in DataManReg.cc.
382  // This function gets automatically invoked by the table system.
384  const Record& spec);
385 
386  // Convert the rownr to the rownr in the underlying table.
387  rownr_t convertRownr (rownr_t rownr);
388 };
389 
390 
392 {
393  if (Int64(rownr) != lastRow_p) {
394  rowNumber_p = rowColumn_p(rownr);
395  lastRow_p = rownr;
396  }
397  return rowNumber_p;
398 }
399 
401  { return enginePtr_p->convertRownr (rownr); }
402 
403 
404 
405 } //# NAMESPACE CASACORE - END
406 
407 #endif
Non-templated base class for templated Array class.
Definition: ArrayBase.h:73
const String & columnName() const
Get rhe column name.
Abstract base class for a data manager.
Definition: DataManager.h:221
Virtual column engine forwarding to other columns.
Definition: ForwardCol.h:405
String dataManagerName() const
Return the name of the data manager.
Virtual column engine forwarding to other columns/rows.
DataManager * clone() const
Clone the engine object.
ForwardColumnIndexedRowEngine(const String &dataManagerName, const Record &spec)
The default constructor is required for reconstruction of the engine when a table is read back.
PtrBlock< ForwardColumnIndexedRow * > refColumns_p
Define the various engine column objects.
static void registerClass()
Register the class name and the static makeObject "constructor".
virtual Record dataManagerSpec() const
Record a record containing data manager specifications.
void reopenRW()
Reopen the engine for read/write access.
void prepare()
Initialize the engine.
~ForwardColumnIndexedRowEngine()
Destructor is mandatory.
void create64(rownr_t initialNrrow)
Initialize the object for a new table.
DataManagerColumn * makeScalarColumn(const String &columnName, int dataType, const String &dataTypeId)
Create the column object for the scalar column in this engine.
ForwardColumnIndexedRowEngine(const ForwardColumnIndexedRowEngine &)
The copy constructor is forbidden (so it is private).
Int64 lastRow_p
Cache of last row used to get row number.
static String className()
Return the name of the class.
ForwardColumnIndexedRowEngine(const Table &referencedTable, const String &rowColumnName)
Create the engine.
DataManagerColumn * makeIndArrColumn(const String &columnName, int dataType, const String &dataTypeId)
Create the column object for the indirect array column in this engine.
ForwardColumnIndexedRowEngine(const Table &referencedTable, const String &rowColumnName, const String &dataManagerName)
Create the engine.
String rowColumnName_p
Define the column with the row numbers (must have data type uInt).
rownr_t convertRownr(rownr_t rownr)
Convert the rownr to the rownr in the underlying table.
String dataManagerType() const
Return the type name of the engine (i.e.
static DataManager * makeObject(const String &dataManagerName, const Record &spec)
Define the "constructor" to construct this engine when a table is read back.
virtual void getString(rownr_t rownr, String *dataPtr)
virtual void putOther(rownr_t rownr, const void *dataPtr)
Put the scalar value with a non-standard data type into the given row.
virtual void getBool(rownr_t rownr, Bool *dataPtr)
Get the scalar value with a standard data type in the given row.
virtual void putuChar(rownr_t rownr, const uChar *dataPtr)
void getArrayV(rownr_t rownr, ArrayBase &dataPtr)
Get the array value in the given row.
virtual void putuShort(rownr_t rownr, const uShort *dataPtr)
virtual void putBool(rownr_t rownr, const Bool *dataPtr)
Put the scalar value with a standard data type into the given row.
virtual void getInt(rownr_t rownr, Int *dataPtr)
void putSliceV(rownr_t rownr, const Slicer &slicer, const ArrayBase &dataPtr)
Put into a section of the array in the given row.
void getSliceV(rownr_t rownr, const Slicer &slicer, ArrayBase &dataPtr)
Get a section of the array in the given row.
ForwardColumnIndexedRow & operator=(const ForwardColumnIndexedRow &)
Assignment is not needed and therefore forbidden (so make it private).
virtual void putInt(rownr_t rownr, const Int *dataPtr)
virtual void getOther(rownr_t rownr, void *dataPtr)
Get the scalar value with a non-standard data type in the given row.
void prepare(const Table &thisTable)
Initialize the object.
virtual void putuInt(rownr_t rownr, const uInt *dataPtr)
virtual void putString(rownr_t rownr, const String *dataPtr)
virtual void getInt64(rownr_t rownr, Int64 *dataPtr)
virtual void getfloat(rownr_t rownr, float *dataPtr)
ForwardColumnIndexedRow(ForwardColumnIndexedRowEngine *enginePtr, const String &columnName, int dataType, const String &dataTypeId, const Table &referencedTable)
Construct it for the given column.
void putArrayV(rownr_t rownr, const ArrayBase &dataPtr)
Put the array value into the given row.
virtual void putShort(rownr_t rownr, const Short *dataPtr)
IPosition shape(rownr_t rownr)
Get the shape of the item in the given row.
virtual void putComplex(rownr_t rownr, const Complex *dataPtr)
ForwardColumnIndexedRow(const ForwardColumnIndexedRow &)
Copy constructor is not needed and therefore forbidden (so make it private).
virtual void getuInt(rownr_t rownr, uInt *dataPtr)
virtual void getuChar(rownr_t rownr, uChar *dataPtr)
ForwardColumnIndexedRowEngine * enginePtr_p
rownr_t convertRownr(rownr_t rownr)
Convert the rownr to the rownr in the underlying table.
virtual void getDComplex(rownr_t rownr, DComplex *dataPtr)
virtual void getuShort(rownr_t rownr, uShort *dataPtr)
virtual void putfloat(rownr_t rownr, const float *dataPtr)
Bool isShapeDefined(rownr_t rownr)
Is the value shape defined in the given row?
~ForwardColumnIndexedRow()
Destructor is mandatory.
void setShape(rownr_t rownr, const IPosition &shape)
Set the shape of an (indirect) array in the given row.
virtual void getComplex(rownr_t rownr, Complex *dataPtr)
virtual void putDComplex(rownr_t rownr, const DComplex *dataPtr)
uInt ndim(rownr_t rownr)
Get the dimensionality of the item in the given row.
Bool canChangeShape() const
This data manager cannot handle changing array shapes.
virtual void getShort(rownr_t rownr, Short *dataPtr)
virtual void putdouble(rownr_t rownr, const double *dataPtr)
virtual void getdouble(rownr_t rownr, double *dataPtr)
virtual void putInt64(rownr_t rownr, const Int64 *dataPtr)
int dataType() const
Get the data type of the column as defined in DataType.h.
String dataTypeId() const
Get the data type id of the column for dataType==TpOther.
A drop-in replacement for Block<T*>.
Definition: Block.h:814
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned char uChar
Definition: aipstype.h:47
short Short
Definition: aipstype.h:48
unsigned int uInt
Definition: aipstype.h:51
unsigned short uShort
Definition: aipstype.h:49
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
int Int
Definition: aipstype.h:50
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