casacore
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 
37 namespace 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 //
101 class LogMessage {
102 public:
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.
140  Priority=NORMAL);
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.
201  String toString() const;
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);
207 private:
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>
224 ostream &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 & line(uInt which)
const LogOrigin & origin() const
Get and set the origin of this LogMessage.
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 Time & messageTime() const
Returns the time at which the message text was created.
LogMessage & origin(const LogOrigin &origin)
LogMessage & message(const String &message, Bool keepLastTime=False)
Set the message text.
LogMessage & operator=(const LogMessage &other)
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.
String toTermString() const
LogMessage(Priority priority=NORMAL)
Create a message with the given priority and the current time, and an empty origin and message.
void copy_other(const LogMessage &other)
Provide common implementation for copy constructor and assignment operator.
const String & message() const
Get the message text.
LogMessage & messageTime(const Time &theTime)
Normally you should not manually set the time, however there may be rare circumstances where it is us...
LogMessage & priority(Priority which)
LogMessage(const LogOrigin &sourceLocation, Priority priority=NORMAL)
Create a message with the given location and priority, the current time and an empty message.
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
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 IComplex &)
Show on ostream.