Debian Codegraph @

src/AbstractAppender.cpp

raw
1 /*
2 Copyright (c) 2010 Boris Moiseev (cyberbobs at gmail dot com)
3
4 This program is free software: you can redistribute it and/or modify
5 it under the terms of the GNU Lesser General Public License version 2.1
6 as published by the Free Software Foundation and appearing in the file
7 LICENSE.LGPL included in the packaging of this file.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU Lesser General Public License for more details.
13 */
14
15 #include "AbstractAppender.h"
16
17 DLOG_CORE_BEGIN_NAMESPACE
18
19 /*!
20 @~english
21 \class Dtk::Core::AbstractAppender
22 \inmodule dtkcore
23
24 \brief The AbstractAppender class provides an abstract base class for writing a log entries.
25
26 The AbstractAppender class is the base interface class for all log appenders that could be used with Logger.
27
28 AbstractAppender provides a common implementation for the thread safe, mutex-protected logging of application
29 messages, such as ConsoleAppender, FileAppender or something else. AbstractAppender is abstract and can not be
30 instantiated, but you can use any of its subclasses or create a custom log appender at your choice.
31
32 Appenders are the logical devices that is aimed to be attached to Logger object by calling
33 Logger::registerAppender(). On each log record call from the application Logger object sequentially calls write()
34 function on all the appenders registered in it.
35
36 You can subclass AbstractAppender to implement a logging target of any kind you like. It may be the external logging
37 subsystem (for example, syslog in *nix), XML file, SQL database entries, D-Bus messages or anything else you can
38 imagine.
39
40 For the simple non-structured plain text logging (for example, to a plain text file or to the console output) you may
41 like to subclass the AbstractStringAppender instead of AbstractAppender, which will give you a more convenient way to
42 control the format of the log output.
43
44 \sa AbstractStringAppender
45 \sa Logger::registerAppender()
46 */
47
48 /*!
49 @~english
50 \brief Constructs a AbstractAppender object.
51 */
52 AbstractAppender::AbstractAppender()
53 : m_detailsLevel(Logger::Debug)
54 {
55 }
56
57 /*!
58 @~english
59 \brief Destructs the AbstractAppender object.
60 */
61 AbstractAppender::~AbstractAppender()
62 {
63 }
64
65 /*!
66 @~english
67 \brief Returns the current details level of appender.
68
69 Log records with a log level lower than a current detailsLevel() will be silently ignored by appender and would not
70 be sent to its append() function.
71
72 It provides additional logging flexibility, allowing you to set the different severity levels for different types
73 of logs.
74
75 \note This function is thread safe.
76
77 \return The log level.
78
79 \sa setDetailsLevel()
80 \sa Logger::LogLevel
81 */
82 Logger::LogLevel AbstractAppender::detailsLevel() const
83 {
84 QMutexLocker locker(&m_detailsLevelMutex);
85 return m_detailsLevel;
86 }
87
88 /*!
89 @~english
90 \brief Sets the current details level of appender.
91
92 Default details \a level is Logger::Debug
93
94 \note This function is thread safe.
95
96 \sa detailsLevel()
97 \sa Logger::LogLevel
98 */
99 void Dtk::Core::AbstractAppender::setDetailsLevel(Logger::LogLevel level)
100 {
101 QMutexLocker locker(&m_detailsLevelMutex);
102 m_detailsLevel = level;
103 }
104
105 /*!
106 @~english
107 \brief Sets the current details \a level of appender.
108
109 This function is provided for convenience, it behaves like an above function.
110
111 \sa detailsLevel()
112 \sa Logger::LogLevel
113 */
114 void AbstractAppender::setDetailsLevel(const QString &level)
115 {
116 setDetailsLevel(Logger::levelFromString(level));
117 }
118
119 /*!
120 @~english
121 \brief Tries to write the log record to this logger.
122
123 This is the function called by Logger object to write a log \a message to the appender.
124
125 The \a time parameter indicates the time stamp.
126 The \a level parameter describes the LogLevel.
127 The \a file parameter is the current file name.
128 The \a line parameter indicates the number of lines to output.
129 The \a func parameter indicates the function name to output.
130 The \a category parameter indicates the log category.
131 The \a msg parameter indicates the output message.
132
133 \note This function is thread safe.
134
135 \sa Logger::write()
136 \sa detailsLevel()
137 */
138 void AbstractAppender::write(const QDateTime &time, Logger::LogLevel level, const char *file, int line, const char *func, const QString &category, const QString &msg)
139 {
140 if (level < detailsLevel())
141 return;
142
143 QMutexLocker locker(&m_writeMutex);
144 append(time, level, file, line, func, category, msg);
145 }
146
147 /*!
148 @~english
149 \fn virtual void AbstractAppender::append(const QDateTime &timeStamp, Logger::LogLevel level, const char *file, int line,
150 const char *function, const QString &category, const QString &message) = 0
151
152 \brief Writes the log record to the logger instance
153
154 This function is called every time when user tries to write a message to this AbstractAppender instance using
155 the write() function. Write function works as proxy and transfers only the messages with log level more or equal
156 to the current logLevel().
157
158 Overload this function when you are implementing a custom appender.
159
160 The \a time parameter indicates the time stamp.
161 The \a level parameter describes the LogLevel.
162 The \a file parameter is the current file name.
163 The \a line parameter indicates the number of lines to output.
164 The \a func parameter indicates the function name to output.
165 The \a category parameter indicates the log category.
166 The \a msg parameter indicates the output message.
167
168 \note This function is not needed to be thread safe because it is never called directly by Logger object. The
169 write() function works as a proxy and protects this function from concurrent access.
170
171 \sa Logger::write()
172 */
173
174 DLOG_CORE_END_NAMESPACE