casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
SubTabDesc.h
Go to the documentation of this file.
00001 //# SubTabDesc.h: Description of columns containing tables
00002 //# Copyright (C) 1994,1995,1996,1997,1999
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: SubTabDesc.h 21051 2011-04-20 11:46:29Z gervandiepen $
00027 
00028 #ifndef TABLES_SUBTABDESC_H
00029 #define TABLES_SUBTABDESC_H
00030 
00031 //# Includes
00032 #include <casa/aips.h>
00033 #include <tables/Tables/BaseColDesc.h>
00034 #include <casa/Containers/SimOrdMap.h>
00035 
00036 namespace casa { //# NAMESPACE CASA - BEGIN
00037 
00038 //# Forward Declarations
00039 class PlainColumn;
00040 class ColumnSet;
00041 class TableDesc;
00042 class String;
00043 class AipsIO;
00044 
00045 
00046 // <summary>
00047 // Description of columns containing tables
00048 // </summary>
00049 
00050 // <use visibility=export>
00051 
00052 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
00053 // </reviewed>
00054 
00055 // <prerequisite>
00056 //# Classes you should understand before using this one.
00057 //   <li> TableDesc
00058 //   <li> BaseColumnDesc
00059 // </prerequisite>
00060 
00061 // <etymology>
00062 // SubTableDesc holds a description of a subtable contained in the
00063 // columns of the parent table.
00064 // </etymology>
00065 
00066 // <synopsis> 
00067 // SubTableDesc describes a table column containing subtables.
00068 // The semantics of subtables are described below.
00069 // The column description is constructed using a table description
00070 // describing the subtable. This subtable decription or its name is
00071 // stored with the column description.
00072 // When a table containing this column gets created, the subtable
00073 // description gets copied and this copy is thereafter frozen.
00074 
00075 // Constructing a column description for a subtable can be done
00076 // in 3 ways:
00077 // <ul>
00078 //  <li> It can be constructed with the name of a table description
00079 //         kept in a file. Only this name will be stored with the column
00080 //         description. Only when the table column gets created,
00081 //         it will read the newest version of this table description.
00082 //         This is a completely dynamic way of defining the column.
00083 //         When the subtable description in the file changes, this column
00084 //         in newly created tables gets the latest version.
00085 //  <li> It can be constructed with a given table description.
00086 //         This means that a copy of that description will be made.
00087 //         The frozen subtable description will be stored with the
00088 //         column description.
00089 //         This is a completely static way of defining the column.
00090 //  <li> It can be constructed with a pointer to a table description.
00091 //         This means that a copy will only be made when the column
00092 //         description gets written. Thus changes to the subtable
00093 //         description will as long as possible be reflected in the
00094 //         column description.
00095 //         This is a mix of the first two ways.
00096 // </ul>
00097 //
00098 // A column can be direct or indirect.
00099 // Direct columns will be written directly in the table file. All cells
00100 // in the column must have the same description and it is therefore not
00101 // possible to change a description.
00102 // The subtables in indirect columns will be stored in separate files.
00103 // The cells in indirect columns can contain different tables. 
00104 // </synopsis> 
00105 
00106 // <example>
00107 // <srcblock>
00108 //     // First build the new description of a subtable.
00109 //     // Define keyword subkey (integer) having value 10.
00110 //     // Define columns ra and dec (double).
00111 //     TableDesc subTableDesc("tTableDesc_sub", "1", TableDesc::New);
00112 //     subTableDesc.keywordSet().keysInt()("subkey") = 10;
00113 //     subTableDesc.addColumn (TpDouble, "ra");
00114 //     subTableDesc.addColumn (TpDouble, "dec");
00115 //
00116 //     // Now create a new table description
00117 //     TableDesc td("tTableDesc", "1", TableDesc::New);
00118 //
00119 //     // Add columns containing subtables.
00120 //     // This is done in 3 slighty different ways, which all have
00121 //     // their own (dis)advantages.
00122 //     // This is described in detail at the SubTableDesc constructors.
00123 //     td.addColumn (SubTableDesc("sub1", "subtable by name","tTableDesc_sub"));
00124 //     td.addColumn (SubTableDesc("sub2", "subtable copy",    subTableDesc));
00125 //     td.addColumn (SubTableDesc("sub3", "subtable pointer", &subTableDesc));
00126 // </srcblock>
00127 // </example>
00128 
00129 // <motivation>
00130 // Several column description classes are needed to allow the user
00131 // to define attributes which are special for each column type.
00132 // For columns containing a table this is the table description.
00133 // </motivation>
00134 
00135 // <todo asof="$DATE:$">
00136 //# A List of bugs, limitations, extensions or planned refinements.
00137 //   <li> Probably only direct table descriptions should be allowed.
00138 //          Indirect arrays can have a shape in the description
00139 //          (although they can have #dim), so tables should behave
00140 //          similarly.
00141 // </todo>
00142 
00143 
00144 class SubTableDesc : public BaseColumnDesc
00145 {
00146 public:
00147 friend class ColumnDesc;
00148 
00149 public:
00150     // Construct from a table description with the given name.
00151     // The description does not need to exist yet. Only when the
00152     // table gets created, the description will be read and must exist.
00153     // This means that the table description is not frozen; the most
00154     // recent description will be used when creating the column.
00155     SubTableDesc (const String& columnName, const String& comment,
00156                   const String& tableDescName, int options = 0);
00157 
00158     // Construct from the given table description, which will be copied
00159     // and frozen.
00160     SubTableDesc (const String& columnName, const String& comment,
00161                   const TableDesc&, int options = 0);
00162 
00163     // Construct from the given table description, which will be used
00164     // directly. The description gets frozen when the column is written.
00165     // Care should be taken, because the given table description must
00166     // not be deleted before the column description gets destructed.
00167     SubTableDesc (const String& columnName, const String& comment,
00168                   TableDesc*, int options = 0);
00169 
00170     // Copy constructor (copy semantics).
00171     SubTableDesc (const SubTableDesc&);
00172 
00173     ~SubTableDesc();
00174 
00175     // Assignment (copy semantics).
00176     SubTableDesc& operator= (const SubTableDesc&);
00177 
00178     // Clone this column description to another.
00179     BaseColumnDesc* clone() const;
00180 
00181     // Get the table description.
00182     // <thrown>
00183     //   <li> TableNoFile
00184     // </thrown>
00185     TableDesc* tableDesc();
00186 
00187     // Get the name of this class.
00188     String className() const;
00189 
00190     // Create a Column column object out of this.
00191     // This is used by class ColumnSet to construct a table column object.
00192     PlainColumn* makeColumn (ColumnSet*) const;
00193 
00194     // Show the column.
00195     void show (ostream& os) const;
00196 
00197     // Create the object from AipsIO (this function is registered).
00198     static BaseColumnDesc* makeDesc(const String& name);
00199 
00200 protected:
00201     // Put the object.
00202     virtual void putDesc (AipsIO&) const;
00203 
00204     // Get the object.
00205     virtual void getDesc (AipsIO&);
00206 
00207 private:
00208     TableDesc*  tabDescPtr_p;               //# pointer to Table Description
00209     String      tabDescTyp_p;               //# type of table description
00210     Bool        byName_p;                   //# True = TableDesc name is given
00211     Bool        allocSelf_p;                //# True = allocated tdptr itself
00212     Bool        shallowCopy_p;              //# True = make shallow copy
00213     //#                                         (is only set when !allocSelf)
00214 
00215     // Read table description (if passed by name).
00216     // If the table description is not found, a False value is returned.
00217     Bool readTableDesc();
00218 
00219     // Handle the addition of the subtable description (clear the flag).
00220     void handleAdd (ColumnDescSet&);
00221 };
00222 
00223 
00224 
00225 } //# NAMESPACE CASA - END
00226 
00227 #endif