casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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);
146  LogMessage &operator=(const LogMessage &other);
147  // </group>
148 
149  ~LogMessage();
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;
169  LogMessage &line(uInt which);
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>
186  Priority priority() const;
187  LogMessage &priority(Priority which);
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;
202  String toTermString() 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
uInt line() const
Get and set the line number in the LogOrigin.
LogMessage & operator=(const LogMessage &other)
ostream & operator<<(ostream &os, const std::pair< T, U > &p)
String toString() const
Turn this entire LogMessage into a String.
Most messages users see should have this priority.
Definition: LogMessage.h:114
Priority priority() const
Get or change the priority of this LogMessage.
const Time & messageTime() const
Returns the time at which the message text was created.
const LogOrigin & origin() const
Get and set the origin of this LogMessage.
Low priority - primarily used for findding problems or tracing execution.
Definition: LogMessage.h:108
const String & message() const
Get the message text.
date and time enquiry functions, with some operations.
Definition: Time.h:88
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
String toTermString() const
const Bool False
Definition: aipstype.h:44
Use messages of warning level to flag things that are unusual and might well be errors.
Definition: LogMessage.h:123
LogOrigin: The source code location of the originator of a LogMessage.
Definition: LogOrigin.h:94
LogMessage & sourceLocation(const SourceLocation *where)
Set the source location - usually this will be called with the macro WHERE.
Priority
An &quot;importance&quot; which is assigned to each LogMessage.
Definition: LogMessage.h:105
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Report on a problem detected by the software.
Definition: LogMessage.h:126
LogMessage(Priority priority=NORMAL)
Create a message with the given priority and the current time, and an empty origin and message...
Informational log messages with with time, priority, and origin.
Definition: LogMessage.h:101
unsigned int uInt
Definition: aipstype.h:51
void copy_other(const LogMessage &other)
Provide common implementation for copy constructor and assignment operator.
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42