casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
VSCEngine.h
Go to the documentation of this file.
1 //# VSCEngine.h: Base virtual column for a scalar 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_VSCENGINE_H
29 #define TABLES_VSCENGINE_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
35 
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 // <summary>
40 // Base virtual column for a scalar 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> VirtualScalarColumn
52 // </prerequisite>
53 
54 // <etymology>
55 // VSCEngine stands for Virtual Scalar Column Engine, i.e. a class
56 // handling a virtual table column containing scalar values.
57 // </etymology>
58 
59 // <synopsis>
60 // VSCEngine 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 // VSCEngine 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 AVSCEngine 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>VSCEngine</src>, where VSC
78 // stands for Virtual Scalar Column (e.g. <src>AVSCEngine</src> for class A).
79 // In this way the default data manager name supplied by the class and by
80 // class ScalarColumnDesc can be used.
81 // </synopsis>
82 
83 // <example>
84 // This example shows the implementation of an engine class AVSCEngine,
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 AVSCEngine functions are shown inline, but they
94 // should be implemented out-of-line in a separate .cc file.
95 // <srcblock>
96 // //# AVSCEngine.h: Example virtual column engine to handle data type A
97 //
98 // #if !defined(AIPS_AVSCENGINE_H)
99 // #define AIPS_AVSCENGINE_H
100 //
101 // //# Includes
102 // #include <casacore/tables/DataMan/VSCEngine.h>
103 // #include <casacore/tables/Tables/ScalarColumn.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 AVSCEngine : public VSCEngine<A>
133 // {
134 // public:
135 //
136 // // The default constructor is required for reconstruction of the
137 // // engine when a table is read back.
138 // AVSCEngine()
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 // AVSCEngine (const String& sourceColumnName,
145 // const String& xTargetColumnName,
146 // const String& yTargetColumnname)
147 // : VSCEngine<A> (sourceColumnName),
148 // xTargetName_p (xTargetColumnName),
149 // yTargetName_p (yTargetColumnName)
150 // {}
151 //
152 // // Destructor is mandatory.
153 // virtual ~AVSCEngine()
154 // {}
155 //
156 // // Clone the object.
157 // virtual DataManager* clone() const
158 // {
159 // DataManager* dmPtr = new AVSCEngine (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 (uInt)
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 (uInt 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 (uInt 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 ("AVSCEngine", makeObject);
206 // }
207 //
208 // private:
209 // // Copy constructor is only used by clone().
210 // // (so it is made private).
211 // AVSCEngine (const AVSCEngine&)
212 // : VSCEngine<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 // AVSCEngine& operator= (const AVSCEngine&);
220 //
221 //
222 // // The target column names.
223 // String xTargetName_p;
224 // String yTargetName_p;
225 // // Objects for the target columns.
226 // ScalarColumn<Int> colx; // used by put
227 // ScalarColumn<Int> rocolx; // used by get
228 // ScalarColumn<float> coly; // used by put
229 // ScalarColumn<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 AVSCEngine();
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 // AVSCEngine::registerClass();
252 // // Create the table description.
253 // TableDesc td;
254 // td.addColumn (ScalarColumnDesc<A>("source"));
255 // td.addColumn (ScalarColumnDesc<Int>("xTarget"));
256 // td.addColumn (ScalarColumnDesc<Int>("yTarget"));
257 // SetupNewTable setup ("table.name", td, Table::New);
258 // // Define the engine for column "source".
259 // AVSCEngine engine ("source", "xTarget", "yTarget");
260 // Table tab (setup, 10);
261 // // Put data into column "source".
262 // ScalarColumn<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 VirtualScalarColumn<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.
300  VSCEngine();
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.
307  ~VSCEngine();
308 
309  // Return the data manager type name.
310  // This defaults to the data type ID followed by VSCEngine
311  // (meaning Virtual Scalar Column Engine).
312  String dataManagerType() const;
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).
322  VSCEngine (const VSCEngine<T>&);
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 scalar 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);
341 
342 
343  //# Now define the data members.
344  String sourceName_p; //# source column name
345 };
346 
347 
348 
349 } //# NAMESPACE CASACORE - END
350 
351 #ifndef CASACORE_NO_AUTO_TEMPLATES
352 #include <casacore/tables/DataMan/VSCEngine.tcc>
353 #endif //# CASACORE_NO_AUTO_TEMPLATES
354 #endif
Abstract base class for virtual column handling.
Definition: VirtColEng.h:111
const String & columnName() const
Get rhe column name.
Definition: DataManager.h:1003
Abstract base class for a column in a data manager.
Definition: DataManager.h:611
const String & sourceColumnName() const
Get the name of the source column.
Definition: VSCEngine.h:315
Templated base class for virtual scalar column.
Definition: VirtScaCol.h:126
~VSCEngine()
Destructor is mandatory.
int dataType() const
Return the data type of the column.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
VSCEngine()
The default constructor is required for reconstruction of the engine when a table is read back...
VSCEngine< T > & operator=(const VSCEngine< T > &)
Assignment is not needed and therefore forbidden (so it is made private).
String dataManagerType() const
Return the data manager type name.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Bool isWritable() const
The column is in principle writable.
Base virtual column for a scalar column with any type.
Definition: VSCEngine.h:288
DataManagerColumn * makeScalarColumn(const String &columnName, int dataType, const String &dataTypeID)
Create the column object for the scalar column in this engine.
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42