casacore
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 
35 namespace 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 {
113 public:
114 
115  // Create the object.
117  {};
118 
120 
121 private:
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.
Definition: DataManager.h:221
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.
virtual DataManagerColumn * makeDirArrColumn(const String &columnName, int dataType, const String &dataTypeId)
Create a direct array column.
VirtualColumnEngine & operator=(const VirtualColumnEngine &)
Assignment cannot be used for this base class.
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.
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