casacore
StManAipsIO.h
Go to the documentation of this file.
1 //# StManAipsIO.h: Storage manager for tables using AipsIO
2 //# Copyright (C) 1994,1995,1996,1997,1998,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: StManAipsIO.h 20551 2009-03-25 00:11:33Z Malte.Marquarding $
27 
28 #ifndef TABLES_STMANAIPSIO_H
29 #define TABLES_STMANAIPSIO_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/DataMan/MSMBase.h>
35 #include <casacore/tables/DataMan/MSMColumn.h>
36 #include <casacore/casa/Containers/Block.h>
37 #include <casacore/casa/BasicSL/Complex.h>
38 #include <casacore/casa/Arrays/IPosition.h>
39 #include <casacore/casa/BasicSL/String.h>
40 #include <casacore/casa/Utilities/DataType.h>
41 #include <casacore/casa/IO/ByteIO.h>
42 
43 namespace casacore { //# NAMESPACE CASACORE - BEGIN
44 
45 //# Forward clarations
46 class AipsIO;
47 class StManAipsIO;
48 class StManArrayFile;
49 
50 
51 // <summary>
52 // AipsIO table column storage manager class
53 // </summary>
54 
55 // <use visibility=local>
56 
57 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
58 // </reviewed>
59 
60 // <prerequisite>
61 //# Classes you should understand before using this one.
62 // <li> DataManagerColumn
63 // </prerequisite>
64 
65 // <etymology>
66 // StManColumnAipsIO handles a column for an AipsIO storage manager.
67 // </etymology>
68 
69 // <synopsis>
70 // StManColumnAipsIO is used by StManAipsIO to handle the access to
71 // the data in a table column.
72 // It is an storage manager based on AipsIO. The entire column is
73 // kept in memory and only written when the storage manager closes.
74 // When the storage manager gets opened, the entire column gets
75 // read back.
76 // It fully supports addition and removal of rows.
77 //
78 // StManColumnAipsIO serves 2 purposes:
79 // <ol>
80 // <li> It handles a column containing scalar values.
81 // <li> It serves as a base class for StManArrayColumnAipsIO and
82 // StManIndArrayColumnAipsIO. These classes handle arrays and
83 // use StManColumnAipsIO to hold a pointer to the array in each row.
84 // </ol>
85 //
86 // StManColumnAipsIO does not hold a column as a consecutive array,
87 // because extending the column (i.e. adding rows) proofed be too
88 // expensive due to the repeated copying involved when creating a table
89 // (this method was used by the old table system).
90 // Instead it has a number of data blocks (extensions) indexed to by a
91 // super block. Accessing a row means finding the appropriate extension
92 // via a binary search. Because there is only 1 extension when a table is
93 // read back, the overhead in finding a row is small.
94 // </synopsis>
95 
96 // <motivation>
97 // StManColumnAipsIO handles the standard data types. The class
98 // is not templated, but a switch statement is used instead.
99 // Templates would cause too many instantiations.
100 // </motivation>
101 
102 // <todo asof="$DATE:$">
103 //# A List of bugs, limitations, extensions or planned refinements.
104 // </todo>
105 
106 
108 {
109 public:
110 
111  // Create a column of the given type.
112  // It will maintain a pointer to its parent storage manager.
114 
115  // Frees up the storage.
117 
118  // Write the column data into AipsIO.
119  // It will successively write all extensions using putData.
120  virtual void putFile (rownr_t nrval, AipsIO&);
121 
122  // Read the column data from AipsIO.
123  // One extension gets allocated to hold all rows in the column.
124  virtual void getFile (rownr_t nrval, AipsIO&);
125 
126 protected:
127  // initData does not do anything (only used in MSMColumn).
128  virtual void initData (void* datap, rownr_t nrval);
129 
130  // Put the data (nrval elements) in an extension (starting at datap)
131  // into AipsIO.
132  virtual void putData (void* datap, uInt nrval, AipsIO&);
133 
134  // Get data (nrval elements) into an extension (starting at datap
135  // plus the given index).
136  virtual void getData (void* datap, uInt index, uInt nrval, AipsIO&,
137  uInt version);
138 
139 private:
140  // Forbid copy constructor.
142 
143  // Forbid assignment.
145 };
146 
147 
148 
149 
150 // <summary>
151 // AipsIO table storage manager class
152 // </summary>
153 
154 // <use visibility=export>
155 
156 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
157 // </reviewed>
158 
159 // <prerequisite>
160 //# Classes you should understand before using this one.
161 // <li> DataManager
162 // <li> StManColumnAipsIO
163 // </prerequisite>
164 
165 // <etymology>
166 // StManAipsIO is the storage manager using AipsIO.
167 // </etymology>
168 
169 // <synopsis>
170 // StManAipsIO is a table storage manager based on AipsIO.
171 // It holds the data in the columns in memory and writes them to
172 // a file when the table gets closed. Only the data of indirect arrays
173 // are directly read/written from/to a file.
174 // It contains pointers to the underlying StManColumnAipsIO objects,
175 // which do the actual data handling.
176 //
177 // The AipsIO storage manager does fully support addition and removal
178 // of rows and columns.
179 //
180 // All data, except indirect columns, for this storage manager are kept
181 // in one file. The file name is the table name appended with
182 // .N_AipsIO, where N is the (unique) storage manager sequence number.
183 // Each column containing indirect arrays is stored in a separate file
184 // using class StManIndArrayColumnAipsIO. The name of such a file is
185 // the storage manager file name appended with _cM, where M is a unique
186 // column sequence number acquired using function uniqueNr().
187 // </synopsis>
188 
189 // <todo asof="$DATE:$">
190 //# A List of bugs, limitations, extensions or planned refinements.
191 // </todo>
192 
193 
194 class StManAipsIO : public MSMBase
195 {
196 public:
197 
198  // Create an AipsIO storage manager.
199  // Its name will be blank.
201 
202  // Create an AipsIO storage manager with the given name.
203  // Its name can be used later in e.g. Table::addColumn to
204  // add a column to this storage manager.
205  // <br> Note that the 2nd constructor is needed for table creation
206  // from a record specification.
207  // <group>
208  StManAipsIO (const String& storageManagerName);
209  StManAipsIO (const String& storageManagerName, const Record&);
210  // </group>
211 
212  virtual ~StManAipsIO();
213 
214  // Clone this object.
215  // It does not clone StManAipsIOColumn objects possibly used.
216  virtual DataManager* clone() const;
217 
218  // Get the type name of the data manager (i.e. StManAipsIO).
219  virtual String dataManagerType() const;
220 
221  // Get a unique column number for the column
222  // (it is only unique for this storage manager).
223  // This is used by StManIndArrayColumnAipsIO to create a unique file name.
225  { return uniqnr_p++; }
226 
227  // Make the object from the string.
228  // This function gets registered in the DataManager "constructor" map.
230  const Record& spec);
231 
232  // Open (if needed) the file for indirect arrays with the given mode.
233  // Return a pointer to the object.
235 
236 
237 private:
238  // Forbid copy constructor.
240 
241  // Forbid assignment.
243 
244  // Flush and optionally fsync the data.
245  // It returns a True status if it had to flush (i.e. if data have changed).
246  virtual Bool flush (AipsIO&, Bool fsync);
247 
248  // Let the storage manager create files as needed for a new table.
249  // This allows a column with an indirect array to create its file.
250  virtual void create64 (rownr_t nrrow);
251 
252  // Open the storage manager file for an existing table and read in
253  // the data and let the StManColumnAipsIO objects read their data.
254  virtual rownr_t open64 (rownr_t nrrow, AipsIO&);
255 
256  // Resync the storage manager with the new file contents.
257  // This is done by clearing the cache.
258  virtual rownr_t resync64 (rownr_t nrrow);
259 
260  // Reopen the storage manager files for read/write.
261  virtual void reopenRW();
262 
263  // The data manager will be deleted (because all its columns are
264  // requested to be deleted).
265  // So clean up the things needed (e.g. delete files).
266  virtual void deleteManager();
267 
268  // Create a column in the storage manager on behalf of a table column.
269  // <group>
270  // Create a scalar column.
271  DataManagerColumn* makeScalarColumn (const String& name, int dataType,
272  const String& dataTypeID);
273  // Create a direct array column.
274  DataManagerColumn* makeDirArrColumn (const String& name, int dataType,
275  const String& dataTypeID);
276  // Create an indirect array column.
277  DataManagerColumn* makeIndArrColumn (const String& name, int dataType,
278  const String& dataTypeID);
279  // </group>
280 
281 
282  // Unique nr for column in this storage manager.
284  // The file containing the indirect arrays.
286 };
287 
288 
289 
290 
291 } //# NAMESPACE CASACORE - END
292 
293 #endif
OpenOption
Define the possible ByteIO open options.
Definition: ByteIO.h:65
Abstract base class for a data manager.
Definition: DataManager.h:221
AipsIO table storage manager class.
Definition: StManAipsIO.h:195
virtual rownr_t open64(rownr_t nrrow, AipsIO &)
Open the storage manager file for an existing table and read in the data and let the StManColumnAipsI...
virtual void deleteManager()
The data manager will be deleted (because all its columns are requested to be deleted).
StManAipsIO()
Create an AipsIO storage manager.
StManArrayFile * iosfile_p
The file containing the indirect arrays.
Definition: StManAipsIO.h:285
virtual rownr_t resync64(rownr_t nrrow)
Resync the storage manager with the new file contents.
DataManagerColumn * makeDirArrColumn(const String &name, int dataType, const String &dataTypeID)
Create a direct array column.
virtual Bool flush(AipsIO &, Bool fsync)
Flush and optionally fsync the data.
uInt uniqnr_p
Unique nr for column in this storage manager.
Definition: StManAipsIO.h:283
StManAipsIO(const String &storageManagerName)
Create an AipsIO storage manager with the given name.
virtual DataManager * clone() const
Clone this object.
virtual void create64(rownr_t nrrow)
Let the storage manager create files as needed for a new table.
virtual String dataManagerType() const
Get the type name of the data manager (i.e.
uInt uniqueNr()
Get a unique column number for the column (it is only unique for this storage manager).
Definition: StManAipsIO.h:224
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
Make the object from the string.
StManAipsIO(const String &storageManagerName, const Record &)
DataManagerColumn * makeScalarColumn(const String &name, int dataType, const String &dataTypeID)
Create a column in the storage manager on behalf of a table column.
DataManagerColumn * makeIndArrColumn(const String &name, int dataType, const String &dataTypeID)
Create an indirect array column.
StManAipsIO(const StManAipsIO &)
Forbid copy constructor.
virtual void reopenRW()
Reopen the storage manager files for read/write.
StManAipsIO & operator=(const StManAipsIO &)
Forbid assignment.
StManArrayFile * openArrayFile(ByteIO::OpenOption opt)
Open (if needed) the file for indirect arrays with the given mode.
virtual void putFile(rownr_t nrval, AipsIO &)
Write the column data into AipsIO.
StManColumnAipsIO(const StManColumnAipsIO &)
Forbid copy constructor.
virtual ~StManColumnAipsIO()
Frees up the storage.
StManColumnAipsIO & operator=(const StManColumnAipsIO &)
Forbid assignment.
virtual void getFile(rownr_t nrval, AipsIO &)
Read the column data from AipsIO.
StManColumnAipsIO(StManAipsIO *stMan, int dataType, Bool byPtr)
Create a column of the given type.
virtual void getData(void *datap, uInt index, uInt nrval, AipsIO &, uInt version)
Get data (nrval elements) into an extension (starting at datap plus the given index).
virtual void initData(void *datap, rownr_t nrval)
initData does not do anything (only used in MSMColumn).
virtual void putData(void *datap, uInt nrval, AipsIO &)
Put the data (nrval elements) in an extension (starting at datap) into AipsIO.
virtual int dataType() const
Return the data type of the column.
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 int uInt
Definition: aipstype.h:51
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