1 /*
2 * Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util.logging;
27
28 import java.io.*;
29 import java.nio.channels.FileChannel;
30 import java.nio.channels.FileLock;
31 import java.security.*;
32
33 /**
34 * Simple file logging <tt>Handler</tt>.
35 * <p>
36 * The <tt>FileHandler</tt> can either write to a specified file,
37 * or it can write to a rotating set of files.
38 * <p>
39 * For a rotating set of files, as each file reaches a given size
40 * limit, it is closed, rotated out, and a new file opened.
41 * Successively older files are named by adding "0", "1", "2",
42 * etc. into the base filename.
43 * <p>
44 * By default buffering is enabled in the IO libraries but each log
45 * record is flushed out when it is complete.
46 * <p>
47 * By default the <tt>XMLFormatter</tt> class is used for formatting.
48 * <p>
49 * <b>Configuration:</b>
50 * By default each <tt>FileHandler</tt> is initialized using the following
51 * <tt>LogManager</tt> configuration properties where <tt><handler-name></tt>
52 * refers to the fully-qualified class name of the handler.
53 * If properties are not defined
54 * (or have invalid values) then the specified default values are used.
55 * <ul>
56 * <li> <handler-name>.level
57 * specifies the default level for the <tt>Handler</tt>
58 * (defaults to <tt>Level.ALL</tt>). </li>
59 * <li> <handler-name>.filter
60 * specifies the name of a <tt>Filter</tt> class to use
61 * (defaults to no <tt>Filter</tt>). </li>
62 * <li> <handler-name>.formatter
63 * specifies the name of a <tt>Formatter</tt> class to use
64 * (defaults to <tt>java.util.logging.XMLFormatter</tt>) </li>
65 * <li> <handler-name>.encoding
66 * the name of the character set encoding to use (defaults to
67 * the default platform encoding). </li>
68 * <li> <handler-name>.limit
69 * specifies an approximate maximum amount to write (in bytes)
70 * to any one file. If this is zero, then there is no limit.
71 * (Defaults to no limit). </li>
72 * <li> <handler-name>.count
73 * specifies how many output files to cycle through (defaults to 1). </li>
74 * <li> <handler-name>.pattern
75 * specifies a pattern for generating the output file name. See
76 * below for details. (Defaults to "%h/java%u.log"). </li>
77 * <li> <handler-name>.append
78 * specifies whether the FileHandler should append onto
79 * any existing files (defaults to false). </li>
80 * </ul>
81 * <p>
82 * For example, the properties for {@code FileHandler} would be:
83 * <ul>
84 * <li> java.util.logging.FileHandler.level=INFO </li>
85 * <li> java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter </li>
86 * </ul>
87 * <p>
88 * For a custom handler, e.g. com.foo.MyHandler, the properties would be:
89 * <ul>
90 * <li> com.foo.MyHandler.level=INFO </li>
91 * <li> com.foo.MyHandler.formatter=java.util.logging.SimpleFormatter </li>
92 * </ul>
93 * <p>
94 * A pattern consists of a string that includes the following special
95 * components that will be replaced at runtime:
96 * <ul>
97 * <li> "/" the local pathname separator </li>
98 * <li> "%t" the system temporary directory </li>
99 * <li> "%h" the value of the "user.home" system property </li>
100 * <li> "%g" the generation number to distinguish rotated logs </li>
101 * <li> "%u" a unique number to resolve conflicts </li>
102 * <li> "%%" translates to a single percent sign "%" </li>
103 * </ul>
104 * If no "%g" field has been specified and the file count is greater
105 * than one, then the generation number will be added to the end of
106 * the generated filename, after a dot.
107 * <p>
108 * Thus for example a pattern of "%t/java%g.log" with a count of 2
109 * would typically cause log files to be written on Solaris to
110 * /var/tmp/java0.log and /var/tmp/java1.log whereas on Windows 95 they
111 * would be typically written to C:\TEMP\java0.log and C:\TEMP\java1.log
112 * <p>
113 * Generation numbers follow the sequence 0, 1, 2, etc.
114 * <p>
115 * Normally the "%u" unique field is set to 0. However, if the <tt>FileHandler</tt>
116 * tries to open the filename and finds the file is currently in use by
117 * another process it will increment the unique number field and try
118 * again. This will be repeated until <tt>FileHandler</tt> finds a file name that
119 * is not currently in use. If there is a conflict and no "%u" field has
120 * been specified, it will be added at the end of the filename after a dot.
121 * (This will be after any automatically added generation number.)
122 * <p>
123 * Thus if three processes were all trying to log to fred%u.%g.txt then
124 * they might end up using fred0.0.txt, fred1.0.txt, fred2.0.txt as
125 * the first file in their rotating sequences.
126 * <p>
127 * Note that the use of unique ids to avoid conflicts is only guaranteed
128 * to work reliably when using a local disk file system.
129 *
130 * @since 1.4
131 */
132
133 public class FileHandler extends StreamHandler {
134 private MeteredStream meter;
135 private boolean append;
136 private int limit; // zero => no limit.
137 private int count;
138 private String pattern;
139 private String lockFileName;
140 private FileOutputStream lockStream;
141 private File files[];
142 private static final int MAX_LOCKS = 100;
143 private static java.util.HashMap<String, String> locks = new java.util.HashMap<>();
144
145 // A metered stream is a subclass of OutputStream that
146 // (a) forwards all its output to a target stream
147 // (b) keeps track of how many bytes have been written
148 private class MeteredStream extends OutputStream {
149 OutputStream out;
150 int written;
151
152 MeteredStream(OutputStream out, int written) {
153 this.out = out;
154 this.written = written;
155 }
156
157 public void write(int b) throws IOException {
158 out.write(b);
159 written++;
160 }
161
162 public void write(byte buff[]) throws IOException {
163 out.write(buff);
164 written += buff.length;
165 }
166
167 public void write(byte buff[], int off, int len) throws IOException {
168 out.write(buff,off,len);
169 written += len;
170 }
171
172 public void flush() throws IOException {
173 out.flush();
174 }
175
176 public void close() throws IOException {
177 out.close();
178 }
179 }
180
181 private void open(File fname, boolean append) throws IOException {
182 int len = 0;
183 if (append) {
184 len = (int)fname.length();
185 }
186 FileOutputStream fout = new FileOutputStream(fname.toString(), append);
187 BufferedOutputStream bout = new BufferedOutputStream(fout);
188 meter = new MeteredStream(bout, len);
189 setOutputStream(meter);
190 }
191
192 // Private method to configure a FileHandler from LogManager
193 // properties and/or default values as specified in the class
194 // javadoc.
195 private void configure() {
196 LogManager manager = LogManager.getLogManager();
197
198 String cname = getClass().getName();
199
200 pattern = manager.getStringProperty(cname + ".pattern", "%h/java%u.log");
201 limit = manager.getIntProperty(cname + ".limit", 0);
202 if (limit < 0) {
203 limit = 0;
204 }
205 count = manager.getIntProperty(cname + ".count", 1);
206 if (count <= 0) {
207 count = 1;
208 }
209 append = manager.getBooleanProperty(cname + ".append", false);
210 setLevel(manager.getLevelProperty(cname + ".level", Level.ALL));
211 setFilter(manager.getFilterProperty(cname + ".filter", null));
212 setFormatter(manager.getFormatterProperty(cname + ".formatter", new XMLFormatter()));
213 try {
214 setEncoding(manager.getStringProperty(cname +".encoding", null));
215 } catch (Exception ex) {
216 try {
217 setEncoding(null);
218 } catch (Exception ex2) {
219 // doing a setEncoding with null should always work.
220 // assert false;
221 }
222 }
223 }
224
225
226 /**
227 * Construct a default <tt>FileHandler</tt>. This will be configured
228 * entirely from <tt>LogManager</tt> properties (or their default values).
229 * <p>
230 * @exception IOException if there are IO problems opening the files.
231 * @exception SecurityException if a security manager exists and if
232 * the caller does not have <tt>LoggingPermission("control"))</tt>.
233 * @exception NullPointerException if pattern property is an empty String.
234 */
235 public FileHandler() throws IOException, SecurityException {
236 checkPermission();
237 configure();
238 openFiles();
239 }
240
241 /**
242 * Initialize a <tt>FileHandler</tt> to write to the given filename.
243 * <p>
244 * The <tt>FileHandler</tt> is configured based on <tt>LogManager</tt>
245 * properties (or their default values) except that the given pattern
246 * argument is used as the filename pattern, the file limit is
247 * set to no limit, and the file count is set to one.
248 * <p>
249 * There is no limit on the amount of data that may be written,
250 * so use this with care.
251 *
252 * @param pattern the name of the output file
253 * @exception IOException if there are IO problems opening the files.
254 * @exception SecurityException if a security manager exists and if
255 * the caller does not have <tt>LoggingPermission("control")</tt>.
256 * @exception IllegalArgumentException if pattern is an empty string
257 */
258 public FileHandler(String pattern) throws IOException, SecurityException {
259 if (pattern.length() < 1 ) {
260 throw new IllegalArgumentException();
261 }
262 checkPermission();
263 configure();
264 this.pattern = pattern;
265 this.limit = 0;
266 this.count = 1;
267 openFiles();
268 }
269
270 /**
271 * Initialize a <tt>FileHandler</tt> to write to the given filename,
272 * with optional append.
273 * <p>
274 * The <tt>FileHandler</tt> is configured based on <tt>LogManager</tt>
275 * properties (or their default values) except that the given pattern
276 * argument is used as the filename pattern, the file limit is
277 * set to no limit, the file count is set to one, and the append
278 * mode is set to the given <tt>append</tt> argument.
279 * <p>
280 * There is no limit on the amount of data that may be written,
281 * so use this with care.
282 *
283 * @param pattern the name of the output file
284 * @param append specifies append mode
285 * @exception IOException if there are IO problems opening the files.
286 * @exception SecurityException if a security manager exists and if
287 * the caller does not have <tt>LoggingPermission("control")</tt>.
288 * @exception IllegalArgumentException if pattern is an empty string
289 */
290 public FileHandler(String pattern, boolean append) throws IOException, SecurityException {
291 if (pattern.length() < 1 ) {
292 throw new IllegalArgumentException();
293 }
294 checkPermission();
295 configure();
296 this.pattern = pattern;
297 this.limit = 0;
298 this.count = 1;
299 this.append = append;
300 openFiles();
301 }
302
303 /**
304 * Initialize a <tt>FileHandler</tt> to write to a set of files. When
305 * (approximately) the given limit has been written to one file,
306 * another file will be opened. The output will cycle through a set
307 * of count files.
308 * <p>
309 * The <tt>FileHandler</tt> is configured based on <tt>LogManager</tt>
310 * properties (or their default values) except that the given pattern
311 * argument is used as the filename pattern, the file limit is
312 * set to the limit argument, and the file count is set to the
313 * given count argument.
314 * <p>
315 * The count must be at least 1.
316 *
317 * @param pattern the pattern for naming the output file
318 * @param limit the maximum number of bytes to write to any one file
319 * @param count the number of files to use
320 * @exception IOException if there are IO problems opening the files.
321 * @exception SecurityException if a security manager exists and if
322 * the caller does not have <tt>LoggingPermission("control")</tt>.
323 * @exception IllegalArgumentException if limit < 0, or count < 1.
324 * @exception IllegalArgumentException if pattern is an empty string
325 */
326 public FileHandler(String pattern, int limit, int count)
327 throws IOException, SecurityException {
328 if (limit < 0 || count < 1 || pattern.length() < 1) {
329 throw new IllegalArgumentException();
330 }
331 checkPermission();
332 configure();
333 this.pattern = pattern;
334 this.limit = limit;
335 this.count = count;
336 openFiles();
337 }
338
339 /**
340 * Initialize a <tt>FileHandler</tt> to write to a set of files
341 * with optional append. When (approximately) the given limit has
342 * been written to one file, another file will be opened. The
343 * output will cycle through a set of count files.
344 * <p>
345 * The <tt>FileHandler</tt> is configured based on <tt>LogManager</tt>
346 * properties (or their default values) except that the given pattern
347 * argument is used as the filename pattern, the file limit is
348 * set to the limit argument, and the file count is set to the
349 * given count argument, and the append mode is set to the given
350 * <tt>append</tt> argument.
351 * <p>
352 * The count must be at least 1.
353 *
354 * @param pattern the pattern for naming the output file
355 * @param limit the maximum number of bytes to write to any one file
356 * @param count the number of files to use
357 * @param append specifies append mode
358 * @exception IOException if there are IO problems opening the files.
359 * @exception SecurityException if a security manager exists and if
360 * the caller does not have <tt>LoggingPermission("control")</tt>.
361 * @exception IllegalArgumentException if limit < 0, or count < 1.
362 * @exception IllegalArgumentException if pattern is an empty string
363 *
364 */
365 public FileHandler(String pattern, int limit, int count, boolean append)
366 throws IOException, SecurityException {
367 if (limit < 0 || count < 1 || pattern.length() < 1) {
368 throw new IllegalArgumentException();
369 }
370 checkPermission();
371 configure();
372 this.pattern = pattern;
373 this.limit = limit;
374 this.count = count;
375 this.append = append;
376 openFiles();
377 }
378
379 // Private method to open the set of output files, based on the
380 // configured instance variables.
381 private void openFiles() throws IOException {
382 LogManager manager = LogManager.getLogManager();
383 manager.checkPermission();
384 if (count < 1) {
385 throw new IllegalArgumentException("file count = " + count);
386 }
387 if (limit < 0) {
388 limit = 0;
389 }
390
391 // We register our own ErrorManager during initialization
392 // so we can record exceptions.
393 InitializationErrorManager em = new InitializationErrorManager();
394 setErrorManager(em);
395
396 // Create a lock file. This grants us exclusive access
397 // to our set of output files, as long as we are alive.
398 int unique = -1;
399 for (;;) {
400 unique++;
401 if (unique > MAX_LOCKS) {
402 throw new IOException("Couldn't get lock for " + pattern);
403 }
404 // Generate a lock file name from the "unique" int.
405 lockFileName = generate(pattern, 0, unique).toString() + ".lck";
406 // Now try to lock that filename.
407 // Because some systems (e.g., Solaris) can only do file locks
408 // between processes (and not within a process), we first check
409 // if we ourself already have the file locked.
410 synchronized(locks) {
411 if (locks.get(lockFileName) != null) {
412 // We already own this lock, for a different FileHandler
413 // object. Try again.
414 continue;
415 }
416 FileChannel fc;
417 try {
418 lockStream = new FileOutputStream(lockFileName);
419 fc = lockStream.getChannel();
420 } catch (IOException ix) {
421 // We got an IOException while trying to open the file.
422 // Try the next file.
423 continue;
424 }
425 boolean available;
426 try {
427 available = fc.tryLock() != null;
428 // We got the lock OK.
429 } catch (IOException ix) {
430 // We got an IOException while trying to get the lock.
431 // This normally indicates that locking is not supported
432 // on the target directory. We have to proceed without
433 // getting a lock. Drop through.
434 available = true;
435 }
436 if (available) {
437 // We got the lock. Remember it.
438 locks.put(lockFileName, lockFileName);
439 break;
440 }
441
442 // We failed to get the lock. Try next file.
443 fc.close();
444 }
445 }
446
447 files = new File[count];
448 for (int i = 0; i < count; i++) {
449 files[i] = generate(pattern, i, unique);
450 }
451
452 // Create the initial log file.
453 if (append) {
454 open(files[0], true);
455 } else {
456 rotate();
457 }
458
459 // Did we detect any exceptions during initialization?
460 Exception ex = em.lastException;
461 if (ex != null) {
462 if (ex instanceof IOException) {
463 throw (IOException) ex;
464 } else if (ex instanceof SecurityException) {
465 throw (SecurityException) ex;
466 } else {
467 throw new IOException("Exception: " + ex);
468 }
469 }
470
471 // Install the normal default ErrorManager.
472 setErrorManager(new ErrorManager());
473 }
474
475 // Generate a filename from a pattern.
476 private File generate(String pattern, int generation, int unique) throws IOException {
477 File file = null;
478 String word = "";
479 int ix = 0;
480 boolean sawg = false;
481 boolean sawu = false;
482 while (ix < pattern.length()) {
483 char ch = pattern.charAt(ix);
484 ix++;
485 char ch2 = 0;
486 if (ix < pattern.length()) {
487 ch2 = Character.toLowerCase(pattern.charAt(ix));
488 }
489 if (ch == '/') {
490 if (file == null) {
491 file = new File(word);
492 } else {
493 file = new File(file, word);
494 }
495 word = "";
496 continue;
497 } else if (ch == '%') {
498 if (ch2 == 't') {
499 String tmpDir = System.getProperty("java.io.tmpdir");
500 if (tmpDir == null) {
501 tmpDir = System.getProperty("user.home");
502 }
503 file = new File(tmpDir);
504 ix++;
505 word = "";
506 continue;
507 } else if (ch2 == 'h') {
508 file = new File(System.getProperty("user.home"));
509 if (isSetUID()) {
510 // Ok, we are in a set UID program. For safety's sake
511 // we disallow attempts to open files relative to %h.
512 throw new IOException("can't use %h in set UID program");
513 }
514 ix++;
515 word = "";
516 continue;
517 } else if (ch2 == 'g') {
518 word = word + generation;
519 sawg = true;
520 ix++;
521 continue;
522 } else if (ch2 == 'u') {
523 word = word + unique;
524 sawu = true;
525 ix++;
526 continue;
527 } else if (ch2 == '%') {
528 word = word + "%";
529 ix++;
530 continue;
531 }
532 }
533 word = word + ch;
534 }
535 if (count > 1 && !sawg) {
536 word = word + "." + generation;
537 }
538 if (unique > 0 && !sawu) {
539 word = word + "." + unique;
540 }
541 if (word.length() > 0) {
542 if (file == null) {
543 file = new File(word);
544 } else {
545 file = new File(file, word);
546 }
547 }
548 return file;
549 }
550
551 // Rotate the set of output files
552 private synchronized void rotate() {
553 Level oldLevel = getLevel();
554 setLevel(Level.OFF);
555
556 super.close();
557 for (int i = count-2; i >= 0; i--) {
558 File f1 = files[i];
559 File f2 = files[i+1];
560 if (f1.exists()) {
561 if (f2.exists()) {
562 f2.delete();
563 }
564 f1.renameTo(f2);
565 }
566 }
567 try {
568 open(files[0], false);
569 } catch (IOException ix) {
570 // We don't want to throw an exception here, but we
571 // report the exception to any registered ErrorManager.
572 reportError(null, ix, ErrorManager.OPEN_FAILURE);
573
574 }
575 setLevel(oldLevel);
576 }
577
578 /**
579 * Format and publish a <tt>LogRecord</tt>.
580 *
581 * @param record description of the log event. A null record is
582 * silently ignored and is not published
583 */
584 public synchronized void publish(LogRecord record) {
585 if (!isLoggable(record)) {
586 return;
587 }
588 super.publish(record);
589 flush();
590 if (limit > 0 && meter.written >= limit) {
591 // We performed access checks in the "init" method to make sure
592 // we are only initialized from trusted code. So we assume
593 // it is OK to write the target files, even if we are
594 // currently being called from untrusted code.
595 // So it is safe to raise privilege here.
596 AccessController.doPrivileged(new PrivilegedAction<Object>() {
597 public Object run() {
598 rotate();
599 return null;
600 }
601 });
602 }
603 }
604
605 /**
606 * Close all the files.
607 *
608 * @exception SecurityException if a security manager exists and if
609 * the caller does not have <tt>LoggingPermission("control")</tt>.
610 */
611 public synchronized void close() throws SecurityException {
612 super.close();
613 // Unlock any lock file.
614 if (lockFileName == null) {
615 return;
616 }
617 try {
618 // Closing the lock file's FileOutputStream will close
619 // the underlying channel and free any locks.
620 lockStream.close();
621 } catch (Exception ex) {
622 // Problems closing the stream. Punt.
623 }
624 synchronized(locks) {
625 locks.remove(lockFileName);
626 }
627 new File(lockFileName).delete();
628 lockFileName = null;
629 lockStream = null;
630 }
631
632 private static class InitializationErrorManager extends ErrorManager {
633 Exception lastException;
634 public void error(String msg, Exception ex, int code) {
635 lastException = ex;
636 }
637 }
638
639 // Private native method to check if we are in a set UID program.
640 private static native boolean isSetUID();
641 }