casacore
TableKeyword.h
Go to the documentation of this file.
1 //# TableKeyword.h: A keyword value representing a table
2 //# Copyright (C) 1996,1997,1999,2000,2001,2002
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_TABLEKEYWORD_H
29 #define TABLES_TABLEKEYWORD_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/Tables/TableAttr.h>
34 #include <casacore/casa/BasicSL/String.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class Table;
40 
41 
42 // <summary>
43 // Keyword value representing a table
44 // </summary>
45 
46 // <use visibility=local>
47 
48 // <reviewed reviewer="Mark Wieringa" date="1996/04/15" tests="tTableRecord">
49 // </reviewed>
50 
51 // <prerequisite>
52 //# Classes you should understand before using this one.
53 // <li> <linkto class=TableRecord>TableRecord</linkto>
54 // <li> <linkto class=Table>Table</linkto>
55 // </prerequisite>
56 
57 // <synopsis>
58 // TableKeyword represents a record keyword field containing a table.
59 // It is used by class TableRecord, which in its turn is meant to be
60 // used by the Table class.
61 // It serves the following purposes:
62 // <ul>
63 // <li> A table is only opened on demand, i.e. when the keyword
64 // is accessed for the first time. When opened, the function
65 // closeTable makes it possible to close a table when not
66 // needed anymore (provided the table is not used elsewhere).
67 // It will automatically be reopened when used again.
68 // <li> A switch is maintained which indicates if the table
69 // should be opened as readonly or read/write.
70 // A table is opened as read/write when the switch is read/write and
71 // when the table is writable. Otherwise it is opened as readonly.
72 // When a parent table is read back, its TableKeyword's will be
73 // read back and the switch will be set to the access-mode
74 // (readonly or read/write) of the parent table.
75 // When a new table is inserted, the access-mode is taken from the table.
76 // <li> When the parent table is reopened as read/write, the table in
77 // this object will also be reopened as read/write (if the table is
78 // writable).
79 // <li> When a TableKeyword gets written, only the table name will be
80 // written. Reading it back will set the correct access-mode, while
81 // the table will not be opened until necessary.
82 // However, when reading a parent table back it is possible that it
83 // is done from a different directory than where it was created.
84 // Therefore the directory of the parent table is prepended to the
85 // TableKeyword subtable name. Similarly, when written it is stripped off.
86 // <br>E.g. parent table XX and subtable SUB are created in the working
87 // directory WD. Reading back is done from another directory by
88 // specifying WD/XX. WD will be prepended to SUB.
89 // </ul>
90 // </synopsis>
91 
92 // <motivation>
93 // This class provides the extra functionality for keywords containing
94 // tables. This is needed because tables are much more complex entities
95 // than scalars or arrays.
96 // </motivation>
97 
98 // <example>
99 // <srcblock>
100 // // Store a table in the keyword set.
101 // void someFunc (const Table& subTable)
102 // {
103 // // Open the table and get access to the table keyword set.
104 // Table table("table.data", Table::Update);
105 // TableRecord& keyset = table.rwKeywordSet();
106 // keyset.defineTable ("KeyTab", subTable);
107 // }
108 //
109 // // Open the table and get the table from keyword KeyTab.
110 // // It shows that this can be done in one statement.
111 // Table table("table.data");
112 // Table subTab = table.keywordSet().asTable ("KeyTab");
113 // </srcblock>
114 // </example>
115 
116 //# <todo asof="$DATE:$">
117 //# A List of bugs, limitations, extensions or planned refinements.
118 //# </todo>
119 
120 
122 {
123 public:
124  // Construct a TableKeyword with the given tableDescName.
125  // When the tableDescName is empty the keyword is variable structured.
126  // Otherwise it is fixed structured, meaning that only tables with a
127  // description of that name can be assigned to this keyword.
128  TableKeyword (const String& tableDescName);
129 
130  // Construct a TableKeyword from a Table.
131  // <br>
132  // When the tableDescName is empty the keyword is variable structured.
133  // Otherwise it is fixed structured, meaning that only tables with a
134  // description of that name can be assigned to this keyword.
135  TableKeyword (const Table& table, const String& tableDescName);
136 
137  // Copy constructor (full copy semantics).
138  TableKeyword (const TableKeyword& that);
139 
140  // Assignment (leaves tableDescName_p untouched).
141  // This is only possible when both objects conform.
142  // <group>
145  // </group>
146 
148 
149  // Set the name of the table and the writable switch.
150  // This is used when reading back a keyword.
151  void set (const String& name, const TableAttr& parentAttr);
152 
153  // Set the keyword to read/write access.
154  // If the table is already open, it will be reopened with read/write
155  // access if the table is writable.
156  void setRW();
157 
158  // Is the table in use in another process?
159  // If <src>checkSubTables</src> is set, it is also checked if
160  // a subtable is used in another process.
161  Bool isMultiUsed (Bool checkSubTables) const;
162 
163  // Get the name of the table.
164  const String& tableName() const;
165 
166  // Get the name of the table relative to parent table.
167  // <group>
168  String tableName (const String& parentName) const;
169  String tableName (const TableAttr& parentAttr) const
170  { return tableName (parentAttr.name()); }
171  // </group>
172 
173  // Get the table.
174  // It will be opened when necessary.
175  // If given, the lockOptions will be used instead of the ones in
176  // the table attributes.
177  Table table (const TableLock* lockOptions = 0) const;
178 
179  // Get the table attributes.
180  const TableAttr& tableAttributes() const
181  { return attr_p; }
182 
183  // Set the table attributes.
184  void setTableAttributes (const TableAttr& attr)
185  { attr_p = attr; }
186 
187  // Close the table.
188  void close() const;
189 
190  // Flush and optionally fsync the table.
191  void flush (Bool fsync) const;
192 
193  // Rename the table if its path contains the old parent table name.
194  void renameTable (const String& newParentName,
195  const String& oldParentName);
196 
197  // Test if the table in other conforms this table keyword.
198  // It conforms when this description name is blank or matches the
199  // table description name of the other.
200  // <group>
201  Bool conform (const TableKeyword& that) const;
202  Bool conform (const Table& that) const;
203  // </group>
204 
205  // Has the table a fixed description name?
206  // It has when its description name is not empty.
207  Bool isFixed() const;
208 
209 private:
213 };
214 
215 
216 
217 inline const String& TableKeyword::tableName() const
218 {
219  return attr_p.name();
220 }
221 
223 {
224  return (! tableDescName_p.empty());
225 }
226 
227 
228 } //# NAMESPACE CASACORE - END
229 
230 #endif
String: the storage and methods of handling collections of characters.
Definition: String.h:225
Bool empty() const
Test for empty.
Definition: String.h:377
const String & name() const
Get info.
Definition: TableAttr.h:115
Bool conform(const Table &that) const
const String & tableName() const
Get the name of the table.
Definition: TableKeyword.h:217
void close() const
Close the table.
TableKeyword & operator=(const TableKeyword &that)
Assignment (leaves tableDescName_p untouched).
TableKeyword(const String &tableDescName)
Construct a TableKeyword with the given tableDescName.
String tableName(const TableAttr &parentAttr) const
Definition: TableKeyword.h:169
void setTableAttributes(const TableAttr &attr)
Set the table attributes.
Definition: TableKeyword.h:184
Bool isMultiUsed(Bool checkSubTables) const
Is the table in use in another process? If checkSubTables is set, it is also checked if a subtable is...
Bool conform(const TableKeyword &that) const
Test if the table in other conforms this table keyword.
void renameTable(const String &newParentName, const String &oldParentName)
Rename the table if its path contains the old parent table name.
String tableName(const String &parentName) const
Get the name of the table relative to parent table.
void setRW()
Set the keyword to read/write access.
void set(const String &name, const TableAttr &parentAttr)
Set the name of the table and the writable switch.
const TableAttr & tableAttributes() const
Get the table attributes.
Definition: TableKeyword.h:180
TableKeyword(const Table &table, const String &tableDescName)
Construct a TableKeyword from a Table.
Table table(const TableLock *lockOptions=0) const
Get the table.
void flush(Bool fsync) const
Flush and optionally fsync the table.
Bool isFixed() const
Has the table a fixed description name? It has when its description name is not empty.
Definition: TableKeyword.h:222
TableKeyword(const TableKeyword &that)
Copy constructor (full copy semantics).
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