casacore
TiledColumnStMan.h
Go to the documentation of this file.
1 //# TiledColumnStMan.h: Tiled Column Storage Manager
2 //# Copyright (C) 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_TILEDCOLUMNSTMAN_H
29 #define TABLES_TILEDCOLUMNSTMAN_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/DataMan/TiledStMan.h>
34 #include <casacore/casa/Arrays/IPosition.h>
35 #include <casacore/casa/BasicSL/String.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 
41 
42 // <summary>
43 // Tiled Column Storage Manager.
44 // </summary>
45 
46 // <use visibility=export>
47 
48 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
49 // </reviewed>
50 
51 // <prerequisite>
52 //# Classes you should understand before using this one.
53 // <li> <linkto class=TiledStMan>TiledStMan</linkto>
54 // <li> <linkto class=TSMCube>TSMCube</linkto>
55 // <li> <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
56 // for a discussion of the maximum cache size
57 // </prerequisite>
58 
59 // <etymology>
60 // TiledColumnStMan is the Tiled Storage Manager storing
61 // an entire column as one hypercube.
62 // </etymology>
63 
64 // <synopsis>
65 // TiledColumnStMan is a derivation from TiledStMan, the abstract
66 // tiled storage manager class. A description of the basics
67 // of tiled storage managers is given in the
68 // <linkto module=Tables:TiledStMan>Tables module</linkto> description.
69 // <p>
70 // TiledColumnStMan allows the user to create a tiled hypercube for
71 // an entire data column and extend it in an automatic way.
72 // It is meant to be used for fixed shaped data which have to
73 // be accessed in various directions.
74 // <p>
75 // The TiledColumnStMan has the following (extra) properties:
76 // <ul>
77 // <li> Addition of a row results in the extension of the hypercube.
78 // The data cells in all rows have to have the same shape. Therefore
79 // the columns stored by a TiledColumnStMan storage manager
80 // have to be fixed shaped (i.e. FixedShape attribute set in their
81 // column descriptions).
82 // <li> Coordinates for the hypercubes can be defined and (of course)
83 // their shapes have to match the hypercube shape.
84 // Their values have to be put explicitly (so it is not possible
85 // to define them via an extendHypercube call like in
86 // <linkto class=TiledDataStMan>TiledDataStMan</linkto>).
87 // <li> The tile shape of the hypercube has to be defined by means
88 // of the TiledColumnStMan constructor.
89 // </ul>
90 // </synopsis>
91 
92 // <motivation>
93 // This tiled storage manager does not require any special action
94 // (like calling add/extendHypercube) when used with a column
95 // containing equally shaped arrays.
96 // </motivation>
97 
98 // <example>
99 // <srcblock>
100 // // Define the table description and the columns in it.
101 // TableDesc td ("", "1", TableDesc::Scratch);
102 // td.addColumn (ArrayColumnDesc<float> ("RA", 1));
103 // td.addColumn (ArrayColumnDesc<float> ("Dec", 1));
104 // td.addColumn (ScalarColumnDesc<float> ("Velocity"));
105 // td.addColumn (ArrayColumnDesc<float> ("Image", 2));
106 // // Define the 3-dim hypercolumn with its data and coordinate columns.
107 // // Note that its dimensionality must be one higher than the dimensionality
108 // // of the data cells.
109 // td.defineHypercolumn ("TSMExample",
110 // 3,
111 // stringToVector ("Image"),
112 // stringToVector ("RA,Dec,Velocity"));
113 // // Now create a new table from the description.
114 // SetupNewTable newtab("tTiledColumnStMan_tmp.data", td, Table::New);
115 // // Create a TiledColumnStMan storage manager for the hypercolumn
116 // // and bind the columns to it.
117 // // The tile shape has to be specified for the storage manager.
118 // TiledColumnStMan sm1 ("TSMExample", IPosition(3,16,32,32));
119 // newtab.bindAll (sm1);
120 // // Create the table.
121 // Table table(newtab);
122 // // Define the values for the coordinates of the hypercube.
123 // Vector<float> raValues(512);
124 // Vector<float> DecValues(512);
125 // indgen (raValues);
126 // indgen (decValues, float(100));
127 // ArrayColumn<float> ra (table, "RA");
128 // ArrayColumn<float> dec (table, "Dec");
129 // ScalarColumn<float> velocity (table, "Velocity");
130 // ArrayColumn<float> image (table, "Image");
131 // Cube<float> imageValues(IPosition(2,512,512));
132 // indgen (imageValues);
133 // // Write some data into the data columns.
134 // for (uInt i=0; i<64; i++) {
135 // table.addRow();
136 // image.put (i, imageValues);
137 // // The RA and Dec have to be put only once, because they
138 // // are the same for each row.
139 // if (i == 0) {
140 // ra.put (i, raValues);
141 // dec.put (i, decValues);
142 // }
143 // velocity.put (i, float(i));
144 // }
145 // </srcblock>
146 // </example>
147 
148 //# <todo asof="$DATE:$">
149 //# A List of bugs, limitations, extensions or planned refinements.
150 //# </todo>
151 
152 
154 {
155 public:
156  // Create a TiledDataStMan storage manager for the hypercolumn
157  // with the given name. The columns used should have the FixedShape
158  // attribute set.
159  // The hypercolumn name is also the name of the storage manager.
160  // The given tile shape will be used.
161  // The given maximum cache size in bytes (default is unlimited) is
162  // persistent, thus will be reused when the table is read back.
163  // Note that the class
164  // <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
165  // allows one to overwrite the maximum cache size temporarily.
166  // Its description contains a discussion about the effects of
167  // setting a maximum cache.
168  // <br>The constructor taking a Record expects fields in the record with
169  // the name of the arguments in uppercase. If not defined, their
170  // default value is used.
171  // <group>
172  TiledColumnStMan (const String& hypercolumnName,
173  const IPosition& tileShape,
175  TiledColumnStMan (const String& hypercolumnName,
176  const Record& spec);
177  // </group>
178 
180 
181  // Clone this object.
182  // It does not clone TSMColumn objects possibly used.
183  virtual DataManager* clone() const;
184 
185  // TiledColumnStMan can always access a column.
186  virtual Bool canAccessColumn() const;
187 
188  // Get the type name of the data manager (i.e. TiledColumnStMan).
189  virtual String dataManagerType() const;
190 
191  // Make the object from the type name string.
192  // This function gets registered in the DataManager "constructor" map.
194  const Record& spec);
195 
196 private:
197  // Create a TiledColumnStMan.
198  // This constructor is private, because it should only be used
199  // by makeObject.
201 
202  // Forbid copy constructor.
204 
205  // Forbid assignment.
207 
208  // Get the (default) tile shape.
209  virtual IPosition defaultTileShape() const;
210 
211  // Add rows to the storage manager.
212  // This will extend the hypercube.
213  void addRow64 (rownr_t nrrow);
214 
215  // Get the hypercube in which the given row is stored.
216  virtual TSMCube* getHypercube (rownr_t rownr);
217 
218  // Get the hypercube in which the given row is stored.
219  // It also returns the position of the row in that hypercube.
220  virtual TSMCube* getHypercube (rownr_t rownr, IPosition& position);
221 
222  // Check if the hypercolumn definition fits this storage manager.
223  virtual void setupCheck (const TableDesc& tableDesc,
224  const Vector<String>& dataNames) const;
225 
226  // Flush and optionally fsync the data.
227  // It returns a True status if it had to flush (i.e. if data have changed).
228  virtual Bool flush (AipsIO&, Bool fsync);
229 
230  // Let the storage manager create files as needed for a new table.
231  // This allows a column with an indirect array to create its file.
232  virtual void create64 (rownr_t nrrow);
233 
234  // Read the header info.
235  virtual void readHeader (rownr_t nrrow, Bool firstTime);
236 
237 
238  //# Declare data members.
240 };
241 
242 
243 
244 
245 } //# NAMESPACE CASACORE - END
246 
247 #endif
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 create64(rownr_t nrrow)
Let the storage manager create files as needed for a new table.
virtual DataManager * clone() const
Clone this object.
TiledColumnStMan(const String &hypercolumnName, const IPosition &tileShape, uInt64 maximumCacheSize=0)
Create a TiledDataStMan storage manager for the hypercolumn with the given name.
virtual TSMCube * getHypercube(rownr_t rownr, IPosition &position)
Get the hypercube in which the given row is stored.
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
Make the object from the type name string.
virtual Bool canAccessColumn() const
TiledColumnStMan can always access a column.
TiledColumnStMan(const String &hypercolumnName, const Record &spec)
virtual void readHeader(rownr_t nrrow, Bool firstTime)
Read the header info.
TiledColumnStMan & operator=(const TiledColumnStMan &)
Forbid assignment.
virtual TSMCube * getHypercube(rownr_t rownr)
Get the hypercube in which the given row is stored.
virtual Bool flush(AipsIO &, Bool fsync)
Flush and optionally fsync the data.
virtual void setupCheck(const TableDesc &tableDesc, const Vector< String > &dataNames) const
Check if the hypercolumn definition fits this storage manager.
virtual IPosition defaultTileShape() const
Get the (default) tile shape.
TiledColumnStMan()
Create a TiledColumnStMan.
TiledColumnStMan(const TiledColumnStMan &)
Forbid copy constructor.
virtual String dataManagerType() const
Get the type name of the data manager (i.e.
void addRow64(rownr_t nrrow)
Add rows to the storage manager.
uInt maximumCacheSize() const
Get the current maximum cache size (in MiB (MibiByte)).
Definition: TiledStMan.h:532
const IPosition & tileShape(rownr_t rownr) const
Get the tile shape of the data in the given row.
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
unsigned long long uInt64
Definition: aipsxtype.h:39