casacore
SubTabDesc.h
Go to the documentation of this file.
1 //# SubTabDesc.h: Description of columns containing tables
2 //# Copyright (C) 1994,1995,1996,1997,1999
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_SUBTABDESC_H
29 #define TABLES_SUBTABDESC_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/Tables/BaseColDesc.h>
34 #include <casacore/casa/Containers/SimOrdMap.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class PlainColumn;
40 class ColumnSet;
41 class TableDesc;
42 class String;
43 class AipsIO;
44 
45 
46 // <summary>
47 // Description of columns containing tables
48 // </summary>
49 
50 // <use visibility=export>
51 
52 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
53 // </reviewed>
54 
55 // <prerequisite>
56 //# Classes you should understand before using this one.
57 // <li> TableDesc
58 // <li> BaseColumnDesc
59 // </prerequisite>
60 
61 // <etymology>
62 // SubTableDesc holds a description of a subtable contained in the
63 // columns of the parent table.
64 // </etymology>
65 
66 // <synopsis>
67 // SubTableDesc describes a table column containing subtables.
68 // The semantics of subtables are described below.
69 // The column description is constructed using a table description
70 // describing the subtable. This subtable decription or its name is
71 // stored with the column description.
72 // When a table containing this column gets created, the subtable
73 // description gets copied and this copy is thereafter frozen.
74 
75 // Constructing a column description for a subtable can be done
76 // in 3 ways:
77 // <ul>
78 // <li> It can be constructed with the name of a table description
79 // kept in a file. Only this name will be stored with the column
80 // description. Only when the table column gets created,
81 // it will read the newest version of this table description.
82 // This is a completely dynamic way of defining the column.
83 // When the subtable description in the file changes, this column
84 // in newly created tables gets the latest version.
85 // <li> It can be constructed with a given table description.
86 // This means that a copy of that description will be made.
87 // The frozen subtable description will be stored with the
88 // column description.
89 // This is a completely static way of defining the column.
90 // <li> It can be constructed with a pointer to a table description.
91 // This means that a copy will only be made when the column
92 // description gets written. Thus changes to the subtable
93 // description will as long as possible be reflected in the
94 // column description.
95 // This is a mix of the first two ways.
96 // </ul>
97 //
98 // A column can be direct or indirect.
99 // Direct columns will be written directly in the table file. All cells
100 // in the column must have the same description and it is therefore not
101 // possible to change a description.
102 // The subtables in indirect columns will be stored in separate files.
103 // The cells in indirect columns can contain different tables.
104 // </synopsis>
105 
106 // <example>
107 // <srcblock>
108 // // First build the new description of a subtable.
109 // // Define keyword subkey (integer) having value 10.
110 // // Define columns ra and dec (double).
111 // TableDesc subTableDesc("tTableDesc_sub", "1", TableDesc::New);
112 // subTableDesc.keywordSet().keysInt()("subkey") = 10;
113 // subTableDesc.addColumn (TpDouble, "ra");
114 // subTableDesc.addColumn (TpDouble, "dec");
115 //
116 // // Now create a new table description
117 // TableDesc td("tTableDesc", "1", TableDesc::New);
118 //
119 // // Add columns containing subtables.
120 // // This is done in 3 slighty different ways, which all have
121 // // their own (dis)advantages.
122 // // This is described in detail at the SubTableDesc constructors.
123 // td.addColumn (SubTableDesc("sub1", "subtable by name","tTableDesc_sub"));
124 // td.addColumn (SubTableDesc("sub2", "subtable copy", subTableDesc));
125 // td.addColumn (SubTableDesc("sub3", "subtable pointer", &subTableDesc));
126 // </srcblock>
127 // </example>
128 
129 // <motivation>
130 // Several column description classes are needed to allow the user
131 // to define attributes which are special for each column type.
132 // For columns containing a table this is the table description.
133 // </motivation>
134 
135 // <todo asof="$DATE:$">
136 //# A List of bugs, limitations, extensions or planned refinements.
137 // <li> Probably only direct table descriptions should be allowed.
138 // Indirect arrays can have a shape in the description
139 // (although they can have #dim), so tables should behave
140 // similarly.
141 // </todo>
142 
143 
145 {
146 public:
147 friend class ColumnDesc;
148 
149 public:
150  // Construct from a table description with the given name.
151  // The description does not need to exist yet. Only when the
152  // table gets created, the description will be read and must exist.
153  // This means that the table description is not frozen; the most
154  // recent description will be used when creating the column.
155  SubTableDesc (const String& columnName, const String& comment,
156  const String& tableDescName, int options = 0);
157 
158  // Construct from the given table description, which will be copied
159  // and frozen.
160  SubTableDesc (const String& columnName, const String& comment,
161  const TableDesc&, int options = 0);
162 
163  // Construct from the given table description, which will be used
164  // directly. The description gets frozen when the column is written.
165  // Care should be taken, because the given table description must
166  // not be deleted before the column description gets destructed.
167  SubTableDesc (const String& columnName, const String& comment,
168  TableDesc*, int options = 0);
169 
170  // Copy constructor (copy semantics).
171  SubTableDesc (const SubTableDesc&);
172 
173  ~SubTableDesc();
174 
175  // Assignment (copy semantics).
177 
178  // Clone this column description to another.
179  BaseColumnDesc* clone() const;
180 
181  // Get the table description.
182  // <thrown>
183  // <li> TableNoFile
184  // </thrown>
185  TableDesc* tableDesc();
186 
187  // Get the name of this class.
188  String className() const;
189 
190  // Create a Column column object out of this.
191  // This is used by class ColumnSet to construct a table column object.
192  PlainColumn* makeColumn (ColumnSet*) const;
193 
194  // Show the column.
195  void show (ostream& os) const;
196 
197  // Create the object from AipsIO (this function is registered).
198  static BaseColumnDesc* makeDesc(const String& name);
199 
200 protected:
201  // Put the object.
202  virtual void putDesc (AipsIO&) const;
203 
204  // Get the object.
205  virtual void getDesc (AipsIO&);
206 
207 private:
208  TableDesc* tabDescPtr_p; //# pointer to Table Description
209  String tabDescTyp_p; //# type of table description
210  Bool byName_p; //# True = TableDesc name is given
211  Bool allocSelf_p; //# True = allocated tdptr itself
212  Bool shallowCopy_p; //# True = make shallow copy
213  //# (is only set when !allocSelf)
214 
215  // Read table description (if passed by name).
216  // If the table description is not found, a False value is returned.
218 
219  // Handle the addition of the subtable description (clear the flag).
220  void handleAdd (ColumnDescSet&);
221 };
222 
223 
224 
225 } //# NAMESPACE CASACORE - END
226 
227 #endif
SubTableDesc(const String &columnName, const String &comment, const String &tableDescName, int options=0)
Construct from a table description with the given name.
SubTableDesc & operator=(const SubTableDesc &)
Assignment (copy semantics).
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
BaseColumnDesc * clone() const
Clone this column description to another.
An abstract base class for table column descriptions.
Definition: BaseColDesc.h:107
Envelope class for the description of a table column.
Definition: ColumnDesc.h:131
virtual void putDesc(AipsIO &) const
Put the object.
Int options() const
Get the options.
Definition: BaseColDesc.h:181
Class to manage a set of table columns.
Definition: ColumnSet.h:93
const String & name() const
Get the name of the column.
Definition: BaseColDesc.h:138
void show(ostream &os) const
Show the column.
Set of table column descriptions.
Definition: ColDescSet.h:76
Description of columns containing tables.
Definition: SubTabDesc.h:144
static BaseColumnDesc * makeDesc(const String &name)
Create the object from AipsIO (this function is registered).
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
Bool readTableDesc()
Read table description (if passed by name).
Base class for a column in a plain table.
Definition: PlainColumn.h:84
TableDesc * tabDescPtr_p
Definition: SubTabDesc.h:208
String className() const
Get the name of this class.
TableDesc * tableDesc()
Get the table description.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Define the structure of a Casacore table.
Definition: TableDesc.h:186
PlainColumn * makeColumn(ColumnSet *) const
Create a Column column object out of this.
virtual void getDesc(AipsIO &)
Get the object.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
void handleAdd(ColumnDescSet &)
Handle the addition of the subtable description (clear the flag).
const String & comment() const
Get comment string.
Definition: BaseColDesc.h:173