casacore
Loading...
Searching...
No Matches
VirtColEng.h
Go to the documentation of this file.
1//# VirtColEng.h: Abstract base class for virtual column handling
2//# Copyright (C) 1994,1995,1996,1997,1999,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_VIRTCOLENG_H
29#define TABLES_VIRTCOLENG_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/tables/DataMan/DataManager.h>
34
35namespace casacore { //# NAMESPACE CASACORE - BEGIN
36
37//# Forward Declarations
38
39
40// <summary>
41// Abstract base class for virtual column handling
42// </summary>
43
44// <use visibility=local>
45
46// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
47// </reviewed>
48
49// <prerequisite>
50//# Classes you should understand before using this one.
51// <li> DataManager
52// <li> Table
53// </prerequisite>
54
55// <etymology>
56// VirtualColumnEngine is the abstract data manager class for specialized
57// classes (engines) handling a group of virtual columns.
58// </etymology>
59
60// <synopsis>
61// VirtualColumnEngine is the data manager for classes handling
62// a group of virtual columns in tables. It is an abstract base class
63// for the specialized virtual column engines.
64// Each virtual column as such is represented by a class which has
65// to be derived from the abstract base classes VirtualScalarColumn
66// or VirtualArrayColumn. The engine has to create the various
67// column objects via the functions makeXXXColumn.
68//
69// Initialization of the virtual column engine is done by the
70// functions create (for new tables), open (for existing tables) and prepare.
71// The engine can be flushed by the function flush, which allows to
72// write some data. The function open can read these data back.
73// VirtualColumnEngine is closely related with the table system.
74//
75// A number of (pure) virtual functions have been defined. The pure
76// virtual functions must be implemented in the derived class.
77// The non-pure virtual functions have a default implementation throwing
78// a "not possible" exception. They need to be implemented if they
79// are used for this engine (e.g. makeIndArrColumn does not need to
80// be implemented if the engine does not handle arrays).
81// Furthermore the pure virtual function dataManagerType (defined in
82// DataManager.h) has to be implemented. This should return the name
83// of the data manager, which is usually its class name. This name
84// has to be unique; so if the engine is templated, the template
85// parameter has to be part of the data manager name.
86//
87// The engine has to be registered before it can be used by the table system.
88// This means that a special makeObject function has to be made
89// known to the table system, which allows the table system to
90// reconstruct the engine using its name.
91//
92// An example of a virtual column engine can be found in dVirtColEng.{h,cc}
93// in the test directory of the Tables module.
94// Another exanple is class ScaledComplexData.
95// </synopsis>
96
97// <motivation>
98// It is nice if a table column can be expressed as a function
99// of other columns (maybe even in other tables). A virtual column
100// provides this functionality in a very flexible way.
101// A specialized class can calculate the data of a virtual column,
102// but a common base class is required to interface it to the
103// table system.
104// </motivation>
105
106// <todo asof="$DATE:$">
107//# A List of bugs, limitations, extensions or planned refinements.
108// </todo>
109
110
112{
113public:
114
115 // Create the object.
118
120
121private:
122 // The copy constructor cannot be used for this base class.
123 // The clone function should be used instead.
124 // The private declaration of this constructor makes it unusable.
126
127 // Assignment cannot be used for this base class.
128 // The private declaration of this operator makes it unusable.
130
131 // The data manager is not a storage manager?
132 virtual Bool isStorageManager() const;
133
134 // Does the data manager allow to add rows? (default no)
135 virtual Bool canAddRow() const;
136
137 // Does the data manager allow to delete rows? (default no)
138 virtual Bool canRemoveRow() const;
139
140 // Add rows to all columns.
141 // The default implementation does nothing.
142 virtual void addRow64 (rownr_t nrrow);
143
144 // Delete a row from all columns.
145 // The default implementation does nothing.
146 virtual void removeRow64 (rownr_t rownr);
147
148 // Flush the data in the engine object.
149 // If the object contains persistent data, this is the place to write them.
150 // This can be done in two ways:
151 // <ul>
152 // <li>
153 // They can be written in the main table file (using the AipsIO argument).
154 // This should preferably be used if the object contains only little data.
155 // <li>
156 // They can be written in a file of its own. A unique filename
157 // can be acquired using DataManager::fileName().
158 // This way is preferred when the object contains a lot of data.
159 // Possibly this file could already be created in function create
160 // and only be flushed and closed in this function. This allows
161 // getting and putting of data as needed.
162 // </ul>
163 // Another way of storing information is by storing it as a keyword
164 // in the table. In this case it is important to know that close
165 // is called AFTER the keywords are written. Thus, in this way the
166 // information has to be stored and read back in create, open and/or
167 // prepare.
168 // It returns a True status if it had to flush (i.e. if data have changed).
169 // <br>The default implementation does nothing and returns False.
170 virtual Bool flush (AipsIO&, Bool fsync);
171
172 // Resync the storage manager with the new file contents.
173 // This is done by clearing the cache.
174 // The default implementation does nothing.
175 virtual rownr_t resync64 (rownr_t nrrow);
176
177 // Initialize the object for a new table containing initially nrrow rows.
178 // It can be used to initialize variables (possibly using data
179 // from other columns in the table).
180 // The default implementation does nothing.
181 virtual void create64 (rownr_t initialNrrow);
182
183 // Initialize the object for an existing table containing nrrow rows.
184 // It can be used to read values back (written by close) and/or
185 // to initialize variables (possibly using data from other columns
186 // in the table).
187 // The default implementation does nothing.
188 virtual rownr_t open64 (rownr_t nrrow, AipsIO& mainTableFile);
189
190 // Let the data manager initialize itself further.
191 // Prepare is called after create/open has been called for all
192 // columns. In this way one can be sure that referenced columns
193 // are read back and partly initialized.
194 // The default implementation does nothing.
195 virtual void prepare();
196
197 // The data manager will be deleted (because all its columns are
198 // requested to be deleted).
199 // So clean up the things needed (e.g. delete files).
200 // By default it assumes that nothing has to be done.
201 virtual void deleteManager();
202
203 // Make a column object in the engine on behalf of a table column.
204 // This column object class is derived from VirtualScalarColumn
205 // or VirtualArrayColumn. It handles the gets and puts of data.
206 // <group>
207 // Create a scalar column.
208 // The default implementation throws an exception that it cannot
209 // do it for this column.
210 virtual DataManagerColumn* makeScalarColumn (const String& columnName,
211 int dataType,
212 const String& dataTypeId);
213 // Create a direct array column.
214 // The default implementation calls makeIndArrColumn
215 // (when reading the user sees no difference between direct and indirect).
216 virtual DataManagerColumn* makeDirArrColumn (const String& columnName,
217 int dataType,
218 const String& dataTypeId);
219 // Create an indirect array column.
220 // The default implementation throws an exception that it cannot
221 // do it for this column.
222 virtual DataManagerColumn* makeIndArrColumn (const String& columnName,
223 int dataType,
224 const String& dataTypeId);
225 // </group>
226};
227
228
229
230} //# NAMESPACE CASACORE - END
231
232#endif
233
234
235
Abstract base class for a data manager.
String: the storage and methods of handling collections of characters.
Definition String.h:225
virtual void prepare()
Let the data manager initialize itself further.
virtual DataManagerColumn * makeScalarColumn(const String &columnName, int dataType, const String &dataTypeId)
Make a column object in the engine on behalf of a table column.
VirtualColumnEngine()
Create the object.
Definition VirtColEng.h:116
VirtualColumnEngine(const VirtualColumnEngine &that)
The copy constructor cannot be used for this base class.
virtual Bool flush(AipsIO &, Bool fsync)
Flush the data in the engine object.
virtual Bool canRemoveRow() const
Does the data manager allow to delete rows? (default no)
virtual rownr_t open64(rownr_t nrrow, AipsIO &mainTableFile)
Initialize the object for an existing table containing nrrow rows.
virtual Bool isStorageManager() const
The data manager is not a storage manager?
virtual void deleteManager()
The data manager will be deleted (because all its columns are requested to be deleted).
virtual DataManagerColumn * makeIndArrColumn(const String &columnName, int dataType, const String &dataTypeId)
Create an indirect array column.
virtual void removeRow64(rownr_t rownr)
Delete a row from all columns.
virtual rownr_t resync64(rownr_t nrrow)
Resync the storage manager with the new file contents.
VirtualColumnEngine & operator=(const VirtualColumnEngine &)
Assignment cannot be used for this base class.
virtual DataManagerColumn * makeDirArrColumn(const String &columnName, int dataType, const String &dataTypeId)
Create a direct array column.
virtual void addRow64(rownr_t nrrow)
Add rows to all columns.
virtual void create64(rownr_t initialNrrow)
Initialize the object for a new table containing initially nrrow rows.
virtual Bool canAddRow() const
Does the data manager allow to add rows? (default no)
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
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:46