casacore
RecordTransformable.h
Go to the documentation of this file.
1//# RecordTransformable.h: Interface class for converting to/from records
2//# Copyright (C) 1998,1999,2003
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//#
27//# $Id$
28
29#ifndef CASA_RECORDTRANSFORMABLE_H
30#define CASA_RECORDTRANSFORMABLE_H
31
32#include <casacore/casa/aips.h>
33
34namespace casacore { //# NAMESPACE CASACORE - BEGIN
35
36class String;
37class RecordInterface;
38
39// <summary>Interface class for converting to/from records</summary>
40
41// <use visibility=export>
42
43// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tRecordTransformable">
44// </reviewed>
45
46// <prerequisite>
47// <li> <linkto class="RecordInterface">RecordInterface</linkto>
48// </prerequisite>
49//
50// <etymology>
51// This class defines the interface that a class should use if the can be
52// transformed into a record representation.
53// </etymology>
54//
55// <synopsis>
56// This abstract base class is intended to be publicly inherited by classes
57// that contain functions which can represent the object as a record (these
58// functions should be called <src>toRecord</src> and
59// <src>fromRecord</src>). Examples of records are:
60// <ul>
61// <li> <linkto class="Record">Record</linkto>
62// <li> <linkto class="TableRecord">TableRecord</linkto>
63// </ul>
64//
65// This interface defines two functions that convert between a RecordInterface
66// and the class that inherits these functions. These functions are often used
67// to parse input that is beyond the programs control e.g. user input from
68// glish or Table records that may have been generated elsewhere. Hence
69// exceptions should not thrown be thrown by these functions. Instead the
70// function should return False and append an error message to the supplied
71// String when the transformation cannot be accomplished.
72//
73// <note role=warning>
74// Converting to/from a GlishRecord requires an extra step.
75// First a Record should be used which can thereafter be converted to/from
76// a GlishRecord using the appropriate GlishRecord functions.
77// </note>
78// </synopsis>
79//
80// <example>
81// The following example prints out a class using its record representation.
82// This example is in the file tRecordTransformable.cc
83// <srcblock>
84// void printAsRecord(const RecordTransformable & myClass) {
85// String errorMessage;
86// Record rec;
87// if (!myClass.toRecord(errorMessage, rec)) {
88// cout << "Cannot convert class to a Record. The reason is:" << endl;
89// cout << errorMessage << endl;
90// } else {
91// cout << rec.ndefined() << endl;
92// }
93// }
94// </srcblock>
95// </example>
96//
97// <motivation>
98// This class was designed to standardise the function interface for converting
99// between an object and its record representation.
100// </motivation>
101//
102// <todo asof="1998/03/30">
103// <li> Nothing I hope!
104// </todo>
105
107{
108public:
109 // The destructor must be virtual so that the destructor of derived classes
110 // is actually used.
112
113 // Convert the class to an Record representation. The input record may
114 // already contain fields and these fields may be silently overridden. New
115 // fields may be added to the input Record. If the transformation succeeds
116 // then the error String is unchanged and the function returns
117 // True. Otherwise the function returns False and appends an error message to
118 // the supplied String giving the reason why the conversion failed.
119 virtual Bool toRecord(String & error, RecordInterface & outRecord) const = 0;
120
121 // Initialise the class from a Record representation. The input record should
122 // contain the fields that are required by the class. Other fields will be
123 // ignored. If the transformation succeeds then the error String is unchanged
124 // and the function returns True. Otherwise the function returns False and
125 // appends an error message to the supplied String giving the reason why the
126 // conversion failed.
127 virtual Bool fromRecord(String & error, const RecordInterface & inRecord) =0;
128
129 // Initialise the class from a String representation. A string cannot
130 // contain enough information for many objects. Hence the default
131 // implementation of this class returns False, indicating that the class
132 // could not be initialised and an error message is appended to the supplied
133 // string. If the class can be initialised from a string then this function
134 // should be overridden.
135 virtual Bool fromString(String & error, const String & inString);
136
137 // Specify the identification of the record (e.g. 'meas', 'quant'). The
138 // default implementation returns a empty string.
139 virtual const String &ident() const;
140};
141
142
143} //# NAMESPACE CASACORE - END
144
145#endif
virtual Bool fromString(String &error, const String &inString)
Initialise the class from a String representation.
virtual Bool fromRecord(String &error, const RecordInterface &inRecord)=0
Initialise the class from a Record representation.
virtual Bool toRecord(String &error, RecordInterface &outRecord) const =0
Convert the class to an Record representation.
virtual const String & ident() const
Specify the identification of the record (e.g.
virtual ~RecordTransformable()
The destructor must be virtual so that the destructor of derived classes is actually used.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
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