1//
2// FileChannel.h
3//
4// Library: Foundation
5// Package: Logging
6// Module: FileChannel
7//
8// Definition of the FileChannel class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef Foundation_FileChannel_INCLUDED
18#define Foundation_FileChannel_INCLUDED
19
20
21#include "Poco/Foundation.h"
22#include "Poco/Channel.h"
23#include "Poco/Timestamp.h"
24#include "Poco/Timespan.h"
25#include "Poco/Mutex.h"
26
27
28namespace Poco {
29
30
31class LogFile;
32class RotateStrategy;
33class ArchiveStrategy;
34class PurgeStrategy;
35
36
37class Foundation_API FileChannel: public Channel
38 /// A Channel that writes to a file. This class supports
39 /// flexible log file rotation and archiving, as well
40 /// as automatic purging of archived log files.
41 ///
42 /// Only the message's text is written, followed
43 /// by a newline.
44 ///
45 /// Chain this channel to a FormattingChannel with an
46 /// appropriate Formatter to control what is in the text.
47 ///
48 /// The FileChannel support log file rotation based
49 /// on log file size or time intervals.
50 /// Archived log files can be compressed in gzip format.
51 /// Older archived files can be automatically deleted
52 /// (purged).
53 ///
54 /// The rotation strategy can be specified with the
55 /// "rotation" property, which can take one of the
56 /// following values:
57 ///
58 /// * never: no log rotation
59 /// * [day,][hh]:mm: the file is rotated on specified day/time
60 /// day - day is specified as long or short day name (Monday|Mon, Tuesday|Tue, ... );
61 /// day can be omitted, in which case log is rotated every day
62 /// hh - valid hour range is 00-23;
63 /// hour can be omitted, in which case log is rotated every hour
64 /// mm - valid minute range is 00-59;
65 /// minute must be specified
66 /// * daily: the file is rotated daily
67 /// * weekly: the file is rotated every seven days
68 /// * monthly: the file is rotated every 30 days
69 /// * <n> minutes: the file is rotated every <n> minutes,
70 /// where <n> is an integer greater than zero.
71 /// * <n> hours: the file is rotated every <n> hours, where
72 /// <n> is an integer greater than zero.
73 /// * <n> days: the file is rotated every <n> days, where
74 /// <n> is an integer greater than zero.
75 /// * <n> weeks: the file is rotated every <n> weeks, where
76 /// <n> is an integer greater than zero.
77 /// * <n> months: the file is rotated every <n> months, where
78 /// <n> is an integer greater than zero and
79 /// a month has 30 days.
80 /// * <n>: the file is rotated when its size exceeds
81 /// <n> bytes.
82 /// * <n> K: the file is rotated when its size exceeds
83 /// <n> Kilobytes.
84 /// * <n> M: the file is rotated when its size exceeds
85 /// <n> Megabytes.
86 ///
87 /// NOTE: For periodic log file rotation (daily, weekly, monthly, etc.),
88 /// the date and time of log file creation or last rotation is
89 /// written into the first line of the log file. This is because
90 /// there is no reliable way to find out the real creation date of
91 /// a file on many platforms (e.g., most Unix platforms do not
92 /// provide the creation date, and Windows has its own issues
93 /// with its "File System Tunneling Capabilities").
94 ///
95 /// Using the "archive" property it is possible to specify
96 /// how archived log files are named. The following values
97 /// for the "archive" property are supported:
98 ///
99 /// * number: A number, starting with 0, is appended to
100 /// the name of archived log files. The newest
101 /// archived log file always has the number 0.
102 /// For example, if the log file is named
103 /// "access.log", and it fulfils the criteria
104 /// for rotation, the file is renamed to
105 /// "access.log.0". If a file named "access.log.0"
106 /// already exists, it is renamed to "access.log.1",
107 /// and so on.
108 /// * timestamp: A timestamp is appended to the log file name.
109 /// For example, if the log file is named
110 /// "access.log", and it fulfils the criteria
111 /// for rotation, the file is renamed to
112 /// "access.log.20050802110300".
113 ///
114 /// Using the "times" property it is possible to specify
115 /// time mode for the day/time based rotation. The following values
116 /// for the "times" property are supported:
117 ///
118 /// * utc: Rotation strategy is based on UTC time (default).
119 /// * local: Rotation strategy is based on local time.
120 ///
121 /// Archived log files can be compressed using the gzip compression
122 /// method. Compressing can be controlled with the "compress"
123 /// property. The following values for the "compress" property
124 /// are supported:
125 ///
126 /// * true: Compress archived log files.
127 /// * false: Do not compress archived log files.
128 ///
129 /// Archived log files can be automatically purged, either if
130 /// they reach a certain age, or if the number of archived
131 /// log files reaches a given maximum number. This is
132 /// controlled by the purgeAge and purgeCount properties.
133 ///
134 /// The purgeAge property can have the following values:
135 ///
136 /// * <n> [seconds]: the maximum age is <n> seconds.
137 /// * <n> minutes: the maximum age is <n> minutes.
138 /// * <n> hours: the maximum age is <n> hours.
139 /// * <n> days: the maximum age is <n> days.
140 /// * <n> weeks: the maximum age is <n> weeks.
141 /// * <n> months: the maximum age is <n> months, where a month has 30 days.
142 ///
143 /// The purgeCount property has an integer value that specifies the maximum number
144 /// of archived log files. If the number is exceeded, archived log files are
145 /// deleted, starting with the oldest. When "none" or empty string are
146 /// supplied, they reset purgeCount to none (no purging).
147 ///
148 /// The flush property specifies whether each log message is flushed
149 /// immediately to the log file (which may hurt application performance,
150 /// but ensures that everything is in the log in case of a system crash),
151 // or whether it's allowed to stay in the system's file buffer for some time.
152 /// Valid values are:
153 ///
154 /// * true: Every message is immediately flushed to the log file (default).
155 /// * false: Messages are not immediately flushed to the log file.
156 ///
157 /// The rotateOnOpen property specifies whether an existing log file should be
158 /// rotated (and archived) when the channel is opened. Valid values are:
159 ///
160 /// * true: The log file is rotated (and archived) when the channel is opened.
161 /// * false: Log messages will be appended to an existing log file,
162 /// if it exists (unless other conditions for a rotation are met).
163 /// This is the default.
164 ///
165 /// For a more lightweight file channel class, see SimpleFileChannel.
166{
167public:
168 typedef AutoPtr<FileChannel> Ptr;
169
170 FileChannel();
171 /// Creates the FileChannel.
172
173 FileChannel(const std::string& path);
174 /// Creates the FileChannel for a file with the given path.
175
176 void open();
177 /// Opens the FileChannel and creates the log file if necessary.
178
179 void close();
180 /// Closes the FileChannel.
181
182 void log(const Message& msg);
183 /// Logs the given message to the file.
184
185 void setProperty(const std::string& name, const std::string& value);
186 /// Sets the property with the given name.
187 ///
188 /// The following properties are supported:
189 /// * path: The log file's path.
190 /// * rotation: The log file's rotation mode. See the
191 /// FileChannel class for details.
192 /// * archive: The log file's archive mode. See the
193 /// FileChannel class for details.
194 /// * times: The log file's time mode. See the
195 /// FileChannel class for details.
196 /// * compress: Enable or disable compression of
197 /// archived files. See the FileChannel class
198 /// for details.
199 /// * purgeAge: Maximum age of an archived log file before
200 /// it is purged. See the FileChannel class for
201 /// details.
202 /// * purgeCount: Maximum number of archived log files before
203 /// files are purged. See the FileChannel class
204 /// for details.
205 /// * flush: Specifies whether messages are immediately
206 /// flushed to the log file. See the FileChannel class
207 /// for details.
208 /// * rotateOnOpen: Specifies whether an existing log file should be
209 /// rotated and archived when the channel is opened.
210
211 std::string getProperty(const std::string& name) const;
212 /// Returns the value of the property with the given name.
213 /// See setProperty() for a description of the supported
214 /// properties.
215
216 Timestamp creationDate() const;
217 /// Returns the log file's creation date.
218
219 UInt64 size() const;
220 /// Returns the log file's current size in bytes.
221
222 const std::string& path() const;
223 /// Returns the log file's path.
224
225 static const std::string PROP_PATH;
226 static const std::string PROP_ROTATION;
227 static const std::string PROP_ARCHIVE;
228 static const std::string PROP_TIMES;
229 static const std::string PROP_COMPRESS;
230 static const std::string PROP_PURGEAGE;
231 static const std::string PROP_PURGECOUNT;
232 static const std::string PROP_FLUSH;
233 static const std::string PROP_ROTATEONOPEN;
234
235protected:
236 ~FileChannel();
237 void setRotation(const std::string& rotation);
238 void setArchive(const std::string& archive);
239 void setCompress(const std::string& compress);
240 void setPurgeAge(const std::string& age);
241 void setPurgeCount(const std::string& count);
242 void setFlush(const std::string& flush);
243 void setRotateOnOpen(const std::string& rotateOnOpen);
244 void purge();
245
246private:
247 bool setNoPurge(const std::string& value);
248 int extractDigit(const std::string& value, std::string::const_iterator* nextToDigit = NULL) const;
249 void setPurgeStrategy(PurgeStrategy* strategy);
250 Timespan::TimeDiff extractFactor(const std::string& value, std::string::const_iterator start) const;
251
252 std::string _path;
253 std::string _times;
254 std::string _rotation;
255 std::string _archive;
256 bool _compress;
257 std::string _purgeAge;
258 std::string _purgeCount;
259 bool _flush;
260 bool _rotateOnOpen;
261 LogFile* _pFile;
262 RotateStrategy* _pRotateStrategy;
263 ArchiveStrategy* _pArchiveStrategy;
264 PurgeStrategy* _pPurgeStrategy;
265 FastMutex _mutex;
266};
267
268
269} // namespace Poco
270
271
272#endif // Foundation_FileChannel_INCLUDED
273