casacore
Loading...
Searching...
No Matches
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
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39class 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{
123public:
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).
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.
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
209private:
213};
214
215
216
217inline 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.
TableKeyword & operator=(const TableKeyword &that)
Assignment (leaves tableDescName_p untouched).
void close() const
Close the table.
const TableAttr & tableAttributes() const
Get the table attributes.
TableKeyword(const String &tableDescName)
Construct a TableKeyword with the given tableDescName.
String tableName(const TableAttr &parentAttr) const
void setTableAttributes(const TableAttr &attr)
Set the table attributes.
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.
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.
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