casacore
Loading...
Searching...
No Matches
LogMessage.h
Go to the documentation of this file.
1//# LogMessage.h: Informational log messages with with time,priority, and origin
2//# Copyright (C) 1996,1997,1999,2000,2001
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_LOGMESSAGE_H
30#define CASA_LOGMESSAGE_H
31
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Logging/LogOrigin.h>
34#include <casacore/casa/OS/Time.h>
35#include <casacore/casa/iosfwd.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39// <summary>
40// Informational log messages with with time, priority, and origin.
41//</summary>
42
43// <use visibility=export>
44
45// <reviewed reviewer="wbrouw" date="1996/08/21" tests="tLoging.cc" demos="dLogging.cc">
46// </reviewed>
47
48// <prerequisite>
49// <li> <linkto class="LogOrigin">LogOrigin</linkto>
50// </prerequisite>
51//
52// <synopsis>
53// A <src>LogMessage</src> is the unit of information in the Logging system.
54// A LogMessage consists of an informational text (String) message tagged with
55// the following:
56// <ul>
57// <li> The time at which the message was generated ("computer" time, not high
58// precision astronomical time).
59// <li> A priority - one of <src>DEBUGGING</src>, <src>NORMAL</src>,
60// <src>WARN</src>, or <src>SEVERE</src>.
61// <li> A <linkto class="LogOrigin">LogOrigin</linkto>, containing the source
62// code location where the message originated. It also contains the
63// <linkto class="ObjectID">ObjectID</linkto> if the originator was a
64// distributed object. This is mostly of use in debugging.
65// </ul>
66// </synopsis>
67//
68// <example>
69// <srcblock>
70// void globalFunction(Int arg)
71// {
72// LogMessage logMessage(LogOrigin("globalFunction(Int arg)", WHERE));
73// ...
74// logMessage.message("my message").line(__LINE__);
75// ...
76// logMessage.message("my second message").line(__LINE__);
77// ...
78// }
79//
80// void MyClass::member(Int arg)
81// {
82// LogMessage logMessage(LogOrigin("myClass", "member(Int arg)", WHERE));
83// ...
84// logMessage.message("my message").line(__LINE__);
85// ...
86// }
87// </srcblock>
88// A more complete example is available in the module file
89// <linkto module="Logging">Logging.h</linkto>.
90// </example>
91//
92// <todo asof="1996/07/23">
93// <li> Formerly we had a <src>MessageType</src> enum to go along with
94// <src>Priority</src>. It was removed because the categories weren't
95// sufficiently orthogonal. However the idea is probably sound and
96// we might eventually want to put such a categorization back.
97// <li> toRecord() and fromRecord() functions will be needed when we integrate
98// logging with Glish.
99// </todo>
100//
102public:
103 //# If you change this enum, edit toString()
104 // An "importance" which is assigned to each LogMessage.
105 enum Priority {
106 // Low priority - primarily used for findding problems or tracing
107 // execution.
111 // Most messages users see should have this priority. Use for
112 // "interesting" informational messages from normally executing
113 // software.
120 // Use messages of warning level to flag things that are unusual and
121 // might well be errors. Normally the software should proceed anyway
122 // rather than throw an exception.
124 // Report on a problem detected by the software. Messages logged at
125 // this priority will often be followed by a thrown exception.
127
128 // Create a message with the given priority and the current time, and an
129 // empty origin and message.
131
132 // Create a message with the given location and priority, the current time
133 // and an empty message. This will likely be the most commonly used
134 // constructor when a given message is to be used several times in the same
135 // function.
137
138 // Create a completely filled out LogMessage.
141
142 // Make <src>this</src> LogMessage a copy of <src>other</src>. Note that
143 // the time is also copied over.
144 // <group>
145 LogMessage(const LogMessage &other);
147 // </group>
148
150
151 // Get the message text.
152 const String &message() const;
153
154 // Set the message text. If <src>keepLastTime</src> is <src>True</src>, the
155 // previous time will be used, otherwise the current time is used. This is
156 // intended for messages that come out at essentially identical times to
157 // aid in, e.g., Table selections.
158 LogMessage &message(const String &message, Bool keepLastTime = False);
159
160 // Get and set the line number in the
161 // <linkto class="LogOrigin">LogOrigin</linkto>. While in principle you can
162 // get and set this information through the <src>origin()</src> functions,
163 // in practice it is convenient to be able to directly get at the line
164 // number since it and the message text are usually the only things you
165 // change in a particular LogMessage object. Generally you will set the
166 // line number with the <src>__LINE__</src> macro.
167 // <group>
168 uInt line() const;
170 // </group>
171
172 // Set the source location - usually this will be called with the
173 // macro WHERE.
174 LogMessage &sourceLocation(const SourceLocation *where);
175
176 // Get and set the origin of this LogMessage. If you only need the line
177 // number, use the <src>line()</src> or <src>sourceOrigin()</src>
178 // functions instead.
179 // <group>
180 const LogOrigin &origin() const;
182 // </group>
183
184 // Get or change the priority of this LogMessage.
185 // <group>
188 // </group>
189
190 // Returns the time at which the message text was created. This time is
191 // presently "computer operating system" precision time, not high-precision
192 // astronomical time.
193 const Time &messageTime() const;
194
195 // Normally you should not manually set the time, however there may be
196 // rare circumstances where it is useful - for example if you have a single
197 // <src>static</src> message that you want to send out at various times.
198 LogMessage &messageTime(const Time &theTime);
199
200 // Turn this entire LogMessage into a String.
203
204 // Map the given priority into a String - so, for example, it can be stored
205 // in a table.
206 static const String &toString(Priority which);
207private:
212
213 // Provide common implementation for copy constructor and assignment
214 // operator
215 void copy_other(const LogMessage &other);
216};
217
218// <summary>
219// Write a LogMessage to an ostream.
220// </summary>
221// Write a LogMessage as a string to an ostream. Merely calls
222// <src>LogMessage::toString()</src>
223// <group name=LogMessage_ostream>
224ostream &operator<<(ostream &os, const LogMessage &message);
225// </group>
226
227
228
229} //# NAMESPACE CASACORE - END
230
231#endif
LogMessage & sourceLocation(const SourceLocation *where)
Set the source location - usually this will be called with the macro WHERE.
LogMessage(const LogMessage &other)
Make this LogMessage a copy of other.
LogMessage(const String &message, const LogOrigin &sourceLocation, Priority=NORMAL)
Create a completely filled out LogMessage.
LogMessage & priority(Priority which)
LogMessage & message(const String &message, Bool keepLastTime=False)
Set the message text.
const String & message() const
Get the message text.
static const String & toString(Priority which)
Map the given priority into a String - so, for example, it can be stored in a table.
String toString() const
Turn this entire LogMessage into a String.
const LogOrigin & origin() const
Get and set the origin of this LogMessage.
Priority
An "importance" which is assigned to each LogMessage.
Definition LogMessage.h:105
@ WARN
Use messages of warning level to flag things that are unusual and might well be errors.
Definition LogMessage.h:123
@ DEBUGGING
Low priority - primarily used for findding problems or tracing execution.
Definition LogMessage.h:108
@ NORMAL5
Most messages users see should have this priority.
Definition LogMessage.h:114
@ SEVERE
Report on a problem detected by the software.
Definition LogMessage.h:126
uInt line() const
Get and set the line number in the LogOrigin.
LogMessage & origin(const LogOrigin &origin)
String toTermString() const
LogMessage(Priority priority=NORMAL)
Create a message with the given priority and the current time, and an empty origin and message.
LogMessage & line(uInt which)
void copy_other(const LogMessage &other)
Provide common implementation for copy constructor and assignment operator.
LogMessage & messageTime(const Time &theTime)
Normally you should not manually set the time, however there may be rare circumstances where it is us...
const Time & messageTime() const
Returns the time at which the message text was created.
LogMessage(const LogOrigin &sourceLocation, Priority priority=NORMAL)
Create a message with the given location and priority, the current time and an empty message.
LogMessage & operator=(const LogMessage &other)
Priority priority() const
Get or change the priority of this LogMessage.
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
const Bool False
Definition aipstype.h:44
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
unsigned int uInt
Definition aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
ostream & operator<<(ostream &os, const LogMessage &message)