casacore
VACEngine.h
Go to the documentation of this file.
1 //# VACEngine.h: Base virtual column for an array column with any type
2 //# Copyright (C) 1994,1995,1996,1999,2000
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_VACENGINE_H
29 #define TABLES_VACENGINE_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 
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 // <summary>
40 // Base virtual column for an array column with any type
41 // </summary>
42 
43 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
44 // </reviewed>
45 
46 // <use visibility=export>
47 
48 // <prerequisite>
49 //# Classes you should understand before using this one.
50 // <li> VirtualColumnEngine
51 // <li> VirtualArrayColumn
52 // </prerequisite>
53 
54 // <etymology>
55 // VACEngine stands for Virtual Array Column Engine, i.e. a class
56 // handling a virtual table column containing array values.
57 // </etymology>
58 
59 // <synopsis>
60 // VACEngine is a base virtual column engine to handle a column
61 // with an arbitrary type.
62 // Data of columns with standard data types can directly be stored
63 // in a Table using a storage manager, but data of column with non-standard
64 // types have to be stored in another way.
65 // The way to do this is to split the object with the non-standard
66 // type into its individual elements, which are subsequently put into the
67 // appropriate columns.
68 //
69 // A virtual column engine has to be implemented for each non-standard
70 // data type, which has to be stored in a table. This engine has to get
71 // and put the individual parts the object.
72 // VACEngine is the base class for such engines, so the actual
73 // engine quite simple to implement. The example shows the implementation
74 // of an engine AVACEngine handling a data type A.
75 //
76 // In principle the name of the engine class is free, but it is strongly
77 // recommended to use the name <src><dataTypeId>VACEngine</src>, where VAC
78 // stands for Virtual Array Column (e.g. <src>AVACEngine</src> for class A).
79 // In this way the default data manager name supplied by the class and by
80 // class ArrayColumnDesc can be used.
81 // </synopsis>
82 
83 // <example>
84 // This example shows the implementation of an engine class AVACEngine,
85 // which stores the data of a class A.
86 // The data objects A are stored in a column called the source column.
87 // The user has to associate two target columns with it. The engine stores
88 // the data parts x and y in the target columns.
89 // The names of the target columns are stored as keywords in the source
90 // column. In this way the engine can reconstruct itself when the table
91 // is read back.
92 //
93 // In the example all AVACEngine functions are shown inline, but they
94 // should be implemented out-of-line in a separate .cc file.
95 // <srcblock>
96 // //# AVACEngine.h: Example virtual column engine to handle data type A
97 //
98 // #if !defined(AIPS_AVACENGINE_H)
99 // #define AIPS_AVACENGINE_H
100 //
101 // //# Includes
102 // #include <casacore/tables/DataMan/VACEngine.h>
103 // #include <casacore/tables/Tables/ArrayColumn.h>
104 //
105 // // Define the class A.
106 // class A
107 // {
108 // public:
109 // A(): x_p(0), y_p(0) {}
110 // A(Int x, float y) : x_p(x), y_p(y) {}
111 // A(const A& that): x_p(that.x_p), y_p(that.y_p) {}
112 // static String dataTypeId()
113 // { return "A"; }
114 // Int x() const
115 // { return x_p; }
116 // float y() const
117 // { return y_p; }
118 // Int& x()
119 // { return x_p; }
120 // float& y()
121 // { return y_p; }
122 // int operator== (const A& that) const
123 // { return x_p==that.x_p && y_p==that.y_p; }
124 // int operator< (const A& that) const
125 // { return x_p<that.x_p || (x_p==that.x_p && y_p<that.y_p); }
126 // private:
127 // Int x_p;
128 // float y_p;
129 // };
130 //
131 // // Now define the engine to handle objects of type A.
132 // class AVACEngine : public VACEngine<A>
133 // {
134 // public:
135 //
136 // // The default constructor is required for reconstruction of the
137 // // engine when a table is read back.
138 // AVACEngine()
139 // {}
140 //
141 // // Construct the engine for the given source column and storing
142 // // the result in the given target columns for the data members
143 // // x and y of class A.
144 // AVACEngine (const String& sourceColumnName,
145 // const String& xTargetColumnName,
146 // const String& yTargetColumnname)
147 // : VACEngine<A> (sourceColumnName),
148 // xTargetName_p (xTargetColumnName),
149 // yTargetName_p (yTargetColumnName)
150 // {}
151 //
152 // // Destructor is mandatory.
153 // virtual ~AVACEngine()
154 // {}
155 //
156 // // Clone the object.
157 // virtual DataManager* clone() const
158 // {
159 // DataManager* dmPtr = new AVACEngine (sourceColumnName(),
160 // xTargetName_p, yTargetName_p);
161 // return dmPtr;
162 // }
163 //
164 // // Store the target column names in the source column keywords.
165 // virtual void create (rownr_t)
166 // {
167 // TableColumn src (table(), sourceColumnName());
168 // src.keywordSet().keysString()("_xTargetName") = xTargetName_p;
169 // src.keywordSet().keysString()("_yTargetName") = yTargetName_p;
170 // }
171 //
172 // // Prepare the engine by allocating column objects
173 // // for the target columns.
174 // virtual void prepare()
175 // {
176 // TableColumn src (table(), sourceColumnName());
177 // xTargetName_p = src.keywordSet().asString ("_xTargetName");
178 // yTargetName_p = src.keywordSet().asString ("_yTargetName");
179 // rocolx.attach (table(), xTargetName_p);
180 // rocoly.attach (table(), yTargetName_p);
181 // if (table().isWritable()) {
182 // colx.attach (table(), xTargetName_p);
183 // coly.attach (table(), yTargetName_p);
184 // }
185 // }
186 //
187 // // Get the data from a row.
188 // virtual void get (rownr_t rownr, A& value)
189 // {
190 // rocolx.get (rownr, value.x());
191 // rocoly.get (rownr, value.y());
192 // }
193 //
194 // // Put the data in a row.
195 // virtual void put (rownr_t rownr, const A& value)
196 // {
197 // colx.put (rownr, value.x());
198 // coly.put (rownr, value.y());
199 // }
200 //
201 // // Register the class name and the static makeObject "constructor".
202 // // This will make the engine known to the table system.
203 // static void registerClass()
204 // {
205 // DataManager::registerCtor ("AVACEngine", makeObject);
206 // }
207 //
208 // private:
209 // // Copy constructor is only used by clone().
210 // // (so it is made private).
211 // AVACEngine (const AVACEngine&)
212 // : VACEngine<A> (that),
213 // xTargetName_p (that.xTargetName_p),
214 // yTargetName_p (that.yTargetName_p)
215 // {}
216 //
217 // // Assignment is not needed and therefore forbidden
218 // // (so it is made private and is not implemented).
219 // AVACEngine& operator= (const AVACEngine&);
220 //
221 //
222 // // The target column names.
223 // String xTargetName_p;
224 // String yTargetName_p;
225 // // Objects for the target columns.
226 // ArrayColumn<Int> colx; // used by put
227 // ArrayColumn<Int> rocolx; // used by get
228 // ArrayColumn<float> coly; // used by put
229 // ArrayColumn<float> rocoly; // used by get
230 //
231 // public:
232 // // Define the "constructor" to construct this engine when a
233 // // table is read back.
234 // // This "constructor" has to be registered by the user of the engine.
235 // // Function registerClass() is doing that.
236 // static DataManager* makeObject (const String& dataManagerType)
237 // {
238 // DataManager* dmPtr = new AVACEngine();
239 // return dmPtr;
240 // }
241 // };
242 //
243 // #endif
244 // </srcblock>
245 //
246 // User code using this engine to create a new table could look like:
247 // <srcblock>
248 // // Register the engine.
249 // // This is not needed if the engine is registered as part
250 // // of the general DataManager::registerAllCtor function.
251 // AVACEngine::registerClass();
252 // // Create the table description.
253 // TableDesc td;
254 // td.addColumn (ArrayColumnDesc<A>("source"));
255 // td.addColumn (ArrayColumnDesc<Int>("xTarget"));
256 // td.addColumn (ArrayColumnDesc<Int>("yTarget"));
257 // SetupNewTable setup ("table.name", td, Table::New);
258 // // Define the engine for column "source".
259 // AVACEngine engine ("source", "xTarget", "yTarget");
260 // Table tab (setup, 10);
261 // // Put data into column "source".
262 // ArrayColumn<A> col (tab, "source");
263 // for (uInt i=0; i<10; i++) {
264 // col.put (i, someA); // writes indirectly xTarget and yTarget
265 // }
266 // </srcblock>
267 // </example>
268 //
269 // <motivation>
270 // This class makes it easier for the user to implement the engine.
271 // It supplies several default functions.
272 // </motivation>
273 
274 // <templating arg=T>
275 // <li> Default constructor T();
276 // <li> Copy constructor T(const T&);
277 // <li> Assignment operator T& operator= (const T&);
278 // <li> comparison operator int operator== (const T&) const;
279 // <li> comparison operator int operator< (const T&) const;
280 // <li> identification <src>static String dataTypeId();</src>
281 // This should return the (unique) name of the class, thus
282 // when T is templated in its turn, the name should contain the
283 // template argument name.
284 // </templating>
285 
286 
287 template<class T>
289  public VirtualArrayColumn<T>
290 {
291  //# Make members of parent class known.
292 public:
294 
295 public:
296  // The default constructor is required for reconstruction of the
297  // engine when a table is read back.
298  // It is also used to construct an engine, which does not check
299  // the source column name.
301 
302  // Construct an engine to handle a column with an arbitrary data type.
303  // Later it will check if the source column name is correct.
305 
306  // Destructor is mandatory.
308 
309  // Return the data manager type name.
310  // This defaults to the data type ID followed by VACEngine
311  // (meaning Virtual Array Column Engine).
313 
314  // Get the name of the source column.
315  const String& sourceColumnName() const
316  { return sourceName_p; }
317 
318 protected:
319 
320  // Copy constructor is only used by clone().
321  // (so it is made protected).
323 
324 private:
325  // Assignment is not needed and therefore forbidden
326  // (so it is made private).
328 
329  // The column is in principle writable.
330  // This does not mean it is actually writable, because that
331  // depends on the fact if the table is writable.
332  Bool isWritable() const;
333 
334  // Create the column object for the array column in this engine.
335  // It will check if the given column name matches the source
336  // column name. This assures that the engine is bound to the
337  // correct column.
339  int dataType,
340  const String& dataTypeID);
342  int dataType,
343  const String& dataTypeID);
344 
345 
346  //# Now define the data members.
347  String sourceName_p; //# source column name
348 };
349 
350 
351 
352 } //# NAMESPACE CASACORE - END
353 
354 #ifndef CASACORE_NO_AUTO_TEMPLATES
355 #include <casacore/tables/DataMan/VACEngine.tcc>
356 #endif //# CASACORE_NO_AUTO_TEMPLATES
357 #endif
const String & columnName() const
Get rhe column name.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
DataManagerColumn * makeIndArrColumn(const String &columnName, int dataType, const String &dataTypeID)
Create an indirect array column.
Bool isWritable() const
The column is in principle writable.
VACEngine()
The default constructor is required for reconstruction of the engine when a table is read back.
~VACEngine()
Destructor is mandatory.
VACEngine(const String &sourceColumnName)
Construct an engine to handle a column with an arbitrary data type.
VACEngine< T > & operator=(const VACEngine< T > &)
Assignment is not needed and therefore forbidden (so it is made private).
VACEngine(const VACEngine< T > &)
Copy constructor is only used by clone().
String dataManagerType() const
Return the data manager type name.
const String & sourceColumnName() const
Get the name of the source column.
Definition: VACEngine.h:315
DataManagerColumn * makeDirArrColumn(const String &columnName, int dataType, const String &dataTypeID)
Create the column object for the array column in this engine.
virtual int dataType() const
Return the data type of the column.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42