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