1 /* 2 * Copyright (c) 2000, 2015, 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 import java.time.Instant; 28 import java.util.*; 29 import java.util.concurrent.atomic.AtomicInteger; 30 import java.util.concurrent.atomic.AtomicLong; 31 import java.io.*; 32 import java.time.Clock; 33 34 import jdk.internal.misc.JavaLangAccess; 35 import jdk.internal.misc.SharedSecrets; 36 import static sun.util.logger.SimpleConsoleLogger.skipLoggingFrame; 37 38 /** 39 * LogRecord objects are used to pass logging requests between 40 * the logging framework and individual log Handlers. 41 * <p> 42 * When a LogRecord is passed into the logging framework it 43 * logically belongs to the framework and should no longer be 44 * used or updated by the client application. 45 * <p> 46 * Note that if the client application has not specified an 47 * explicit source method name and source class name, then the 48 * LogRecord class will infer them automatically when they are 49 * first accessed (due to a call on getSourceMethodName or 50 * getSourceClassName) by analyzing the call stack. Therefore, 51 * if a logging Handler wants to pass off a LogRecord to another 52 * thread, or to transmit it over RMI, and if it wishes to subsequently 53 * obtain method name or class name information it should call 54 * one of getSourceClassName or getSourceMethodName to force 55 * the values to be filled in. 56 * <p> 57 * <b> Serialization notes:</b> 58 * <ul> 59 * <li>The LogRecord class is serializable. 60 * 61 * <li> Because objects in the parameters array may not be serializable, 62 * during serialization all objects in the parameters array are 63 * written as the corresponding Strings (using Object.toString). 64 * 65 * <li> The ResourceBundle is not transmitted as part of the serialized 66 * form, but the resource bundle name is, and the recipient object's 67 * readObject method will attempt to locate a suitable resource bundle. 68 * 69 * </ul> 70 * 71 * @since 1.4 72 */ 73 74 public class LogRecord implements java.io.Serializable { 75 private static final AtomicLong globalSequenceNumber 76 = new AtomicLong(0); 77 78 /** 79 * The default value of threadID will be the current thread's 80 * thread id, for ease of correlation, unless it is greater than 81 * MIN_SEQUENTIAL_THREAD_ID, in which case we try harder to keep 82 * our promise to keep threadIDs unique by avoiding collisions due 83 * to 32-bit wraparound. Unfortunately, LogRecord.getThreadID() 84 * returns int, while Thread.getId() returns long. 85 */ 86 private static final int MIN_SEQUENTIAL_THREAD_ID = Integer.MAX_VALUE / 2; 87 88 private static final AtomicInteger nextThreadId 89 = new AtomicInteger(MIN_SEQUENTIAL_THREAD_ID); 90 91 private static final ThreadLocal<Integer> threadIds = new ThreadLocal<>(); 92 93 /** 94 * Logging message level 95 */ 96 private Level level; 97 98 /** 99 * Sequence number 100 */ 101 private long sequenceNumber; 102 103 /** 104 * Class that issued logging call 105 */ 106 private String sourceClassName; 107 108 /** 109 * Method that issued logging call 110 */ 111 private String sourceMethodName; 112 113 /** 114 * Non-localized raw message text 115 */ 116 private String message; 117 118 /** 119 * Thread ID for thread that issued logging call. 120 */ 121 private int threadID; 122 123 /** 124 * The Throwable (if any) associated with log message 125 */ 126 private Throwable thrown; 127 128 /** 129 * Name of the source Logger. 130 */ 131 private String loggerName; 132 133 /** 134 * Resource bundle name to localized log message. 135 */ 136 private String resourceBundleName; 137 138 /** 139 * Event time. 140 * @since 1.9 141 */ 142 private Instant instant; 143 144 /** 145 * @serialField level Level Logging message level 146 * @serialField sequenceNumber long Sequence number 147 * @serialField sourceClassName String Class that issued logging call 148 * @serialField sourceMethodName String Method that issued logging call 149 * @serialField message String Non-localized raw message text 150 * @serialField threadID int Thread ID for thread that issued logging call 151 * @serialField millis long Truncated event time in milliseconds since 1970 152 * - calculated as getInstant().toEpochMilli(). 153 * The event time instant can be reconstructed using 154 * <code>Instant.ofEpochSecond(millis/1000, (millis % 1000) * 1000_000 + nanoAdjustment)</code> 155 * @serialField nanoAdjustment int Nanoseconds adjustment to the millisecond of 156 * event time - calculated as getInstant().getNano() % 1000_000 157 * The event time instant can be reconstructed using 158 * <code>Instant.ofEpochSecond(millis/1000, (millis % 1000) * 1000_000 + nanoAdjustment)</code> 159 * <p> 160 * Since: 1.9 161 * @serialField thrown Throwable The Throwable (if any) associated with log 162 * message 163 * @serialField loggerName String Name of the source Logger 164 * @serialField resourceBundleName String Resource bundle name to localized 165 * log message 166 */ 167 private static final ObjectStreamField[] serialPersistentFields = 168 new ObjectStreamField[] { 169 new ObjectStreamField("level", Level.class), 170 new ObjectStreamField("sequenceNumber", long.class), 171 new ObjectStreamField("sourceClassName", String.class), 172 new ObjectStreamField("sourceMethodName", String.class), 173 new ObjectStreamField("message", String.class), 174 new ObjectStreamField("threadID", int.class), 175 new ObjectStreamField("millis", long.class), 176 new ObjectStreamField("nanoAdjustment", int.class), 177 new ObjectStreamField("thrown", Throwable.class), 178 new ObjectStreamField("loggerName", String.class), 179 new ObjectStreamField("resourceBundleName", String.class), 180 }; 181 182 private transient boolean needToInferCaller; 183 private transient Object parameters[]; 184 private transient ResourceBundle resourceBundle; 185 186 /** 187 * Returns the default value for a new LogRecord's threadID. 188 */ 189 private int defaultThreadID() { 190 long tid = Thread.currentThread().getId(); 191 if (tid < MIN_SEQUENTIAL_THREAD_ID) { 192 return (int) tid; 193 } else { 194 Integer id = threadIds.get(); 195 if (id == null) { 196 id = nextThreadId.getAndIncrement(); 197 threadIds.set(id); 198 } 199 return id; 200 } 201 } 202 203 /** 204 * Construct a LogRecord with the given level and message values. 205 * <p> 206 * The sequence property will be initialized with a new unique value. 207 * These sequence values are allocated in increasing order within a VM. 208 * <p> 209 * Since JDK 1.9, the event time is represented by an {@link Instant}. 210 * The instant property will be initialized to the {@linkplain 211 * Instant#now() current instant}, using the best available 212 * {@linkplain Clock#systemUTC() clock} on the system. 213 * <p> 214 * The thread ID property will be initialized with a unique ID for 215 * the current thread. 216 * <p> 217 * All other properties will be initialized to "null". 218 * 219 * @param level a logging level value 220 * @param msg the raw non-localized logging message (may be null) 221 * @see java.time.Clock#systemUTC() 222 */ 223 public LogRecord(Level level, String msg) { 224 this.level = Objects.requireNonNull(level); 225 message = msg; 226 // Assign a thread ID and a unique sequence number. 227 sequenceNumber = globalSequenceNumber.getAndIncrement(); 228 threadID = defaultThreadID(); 229 instant = Instant.now(); 230 needToInferCaller = true; 231 } 232 233 /** 234 * Get the source Logger's name. 235 * 236 * @return source logger name (may be null) 237 */ 238 public String getLoggerName() { 239 return loggerName; 240 } 241 242 /** 243 * Set the source Logger's name. 244 * 245 * @param name the source logger name (may be null) 246 */ 247 public void setLoggerName(String name) { 248 loggerName = name; 249 } 250 251 /** 252 * Get the localization resource bundle 253 * <p> 254 * This is the ResourceBundle that should be used to localize 255 * the message string before formatting it. The result may 256 * be null if the message is not localizable, or if no suitable 257 * ResourceBundle is available. 258 * @return the localization resource bundle 259 */ 260 public ResourceBundle getResourceBundle() { 261 return resourceBundle; 262 } 263 264 /** 265 * Set the localization resource bundle. 266 * 267 * @param bundle localization bundle (may be null) 268 */ 269 public void setResourceBundle(ResourceBundle bundle) { 270 resourceBundle = bundle; 271 } 272 273 /** 274 * Get the localization resource bundle name 275 * <p> 276 * This is the name for the ResourceBundle that should be 277 * used to localize the message string before formatting it. 278 * The result may be null if the message is not localizable. 279 * @return the localization resource bundle name 280 */ 281 public String getResourceBundleName() { 282 return resourceBundleName; 283 } 284 285 /** 286 * Set the localization resource bundle name. 287 * 288 * @param name localization bundle name (may be null) 289 */ 290 public void setResourceBundleName(String name) { 291 resourceBundleName = name; 292 } 293 294 /** 295 * Get the logging message level, for example Level.SEVERE. 296 * @return the logging message level 297 */ 298 public Level getLevel() { 299 return level; 300 } 301 302 /** 303 * Set the logging message level, for example Level.SEVERE. 304 * @param level the logging message level 305 */ 306 public void setLevel(Level level) { 307 if (level == null) { 308 throw new NullPointerException(); 309 } 310 this.level = level; 311 } 312 313 /** 314 * Get the sequence number. 315 * <p> 316 * Sequence numbers are normally assigned in the LogRecord 317 * constructor, which assigns unique sequence numbers to 318 * each new LogRecord in increasing order. 319 * @return the sequence number 320 */ 321 public long getSequenceNumber() { 322 return sequenceNumber; 323 } 324 325 /** 326 * Set the sequence number. 327 * <p> 328 * Sequence numbers are normally assigned in the LogRecord constructor, 329 * so it should not normally be necessary to use this method. 330 * @param seq the sequence number 331 */ 332 public void setSequenceNumber(long seq) { 333 sequenceNumber = seq; 334 } 335 336 /** 337 * Get the name of the class that (allegedly) issued the logging request. 338 * <p> 339 * Note that this sourceClassName is not verified and may be spoofed. 340 * This information may either have been provided as part of the 341 * logging call, or it may have been inferred automatically by the 342 * logging framework. In the latter case, the information may only 343 * be approximate and may in fact describe an earlier call on the 344 * stack frame. 345 * <p> 346 * May be null if no information could be obtained. 347 * 348 * @return the source class name 349 */ 350 public String getSourceClassName() { 351 if (needToInferCaller) { 352 inferCaller(); 353 } 354 return sourceClassName; 355 } 356 357 /** 358 * Set the name of the class that (allegedly) issued the logging request. 359 * 360 * @param sourceClassName the source class name (may be null) 361 */ 362 public void setSourceClassName(String sourceClassName) { 363 this.sourceClassName = sourceClassName; 364 needToInferCaller = false; 365 } 366 367 /** 368 * Get the name of the method that (allegedly) issued the logging request. 369 * <p> 370 * Note that this sourceMethodName is not verified and may be spoofed. 371 * This information may either have been provided as part of the 372 * logging call, or it may have been inferred automatically by the 373 * logging framework. In the latter case, the information may only 374 * be approximate and may in fact describe an earlier call on the 375 * stack frame. 376 * <p> 377 * May be null if no information could be obtained. 378 * 379 * @return the source method name 380 */ 381 public String getSourceMethodName() { 382 if (needToInferCaller) { 383 inferCaller(); 384 } 385 return sourceMethodName; 386 } 387 388 /** 389 * Set the name of the method that (allegedly) issued the logging request. 390 * 391 * @param sourceMethodName the source method name (may be null) 392 */ 393 public void setSourceMethodName(String sourceMethodName) { 394 this.sourceMethodName = sourceMethodName; 395 needToInferCaller = false; 396 } 397 398 /** 399 * Get the "raw" log message, before localization or formatting. 400 * <p> 401 * May be null, which is equivalent to the empty string "". 402 * <p> 403 * This message may be either the final text or a localization key. 404 * <p> 405 * During formatting, if the source logger has a localization 406 * ResourceBundle and if that ResourceBundle has an entry for 407 * this message string, then the message string is replaced 408 * with the localized value. 409 * 410 * @return the raw message string 411 */ 412 public String getMessage() { 413 return message; 414 } 415 416 /** 417 * Set the "raw" log message, before localization or formatting. 418 * 419 * @param message the raw message string (may be null) 420 */ 421 public void setMessage(String message) { 422 this.message = message; 423 } 424 425 /** 426 * Get the parameters to the log message. 427 * 428 * @return the log message parameters. May be null if 429 * there are no parameters. 430 */ 431 public Object[] getParameters() { 432 return parameters; 433 } 434 435 /** 436 * Set the parameters to the log message. 437 * 438 * @param parameters the log message parameters. (may be null) 439 */ 440 public void setParameters(Object parameters[]) { 441 this.parameters = parameters; 442 } 443 444 /** 445 * Get an identifier for the thread where the message originated. 446 * <p> 447 * This is a thread identifier within the Java VM and may or 448 * may not map to any operating system ID. 449 * 450 * @return thread ID 451 */ 452 public int getThreadID() { 453 return threadID; 454 } 455 456 /** 457 * Set an identifier for the thread where the message originated. 458 * @param threadID the thread ID 459 */ 460 public void setThreadID(int threadID) { 461 this.threadID = threadID; 462 } 463 464 /** 465 * Get truncated event time in milliseconds since 1970. 466 * 467 * @return truncated event time in millis since 1970 468 * 469 * @implSpec This is equivalent to calling 470 * {@link #getInstant() getInstant().toEpochMilli()}. 471 * 472 * @deprecated To get the full nanosecond resolution event time, 473 * use {@link #getInstant()}. 474 * 475 * @see #getInstant() 476 */ 477 @Deprecated 478 public long getMillis() { 479 return instant.toEpochMilli(); 480 } 481 482 /** 483 * Set event time. 484 * 485 * @param millis event time in millis since 1970. 486 * 487 * @implSpec This is equivalent to calling 488 * {@link #setInstant(java.time.Instant) 489 * setInstant(Instant.ofEpochMilli(millis))}. 490 * 491 * @deprecated To set event time with nanosecond resolution, 492 * use {@link #setInstant(java.time.Instant)}. 493 * 494 * @see #setInstant(java.time.Instant) 495 */ 496 @Deprecated 497 public void setMillis(long millis) { 498 this.instant = Instant.ofEpochMilli(millis); 499 } 500 501 /** 502 * Gets the instant that the event occurred. 503 * 504 * @return the instant that the event occurred. 505 * 506 * @since 1.9 507 */ 508 public Instant getInstant() { 509 return instant; 510 } 511 512 /** 513 * Sets the instant that the event occurred. 514 * 515 * @param instant the instant that the event occurred. 516 * 517 * @throws NullPointerException if {@code instant} is null. 518 * @since 1.9 519 */ 520 public void setInstant(Instant instant) { 521 this.instant = Objects.requireNonNull(instant); 522 } 523 524 /** 525 * Get any throwable associated with the log record. 526 * <p> 527 * If the event involved an exception, this will be the 528 * exception object. Otherwise null. 529 * 530 * @return a throwable 531 */ 532 public Throwable getThrown() { 533 return thrown; 534 } 535 536 /** 537 * Set a throwable associated with the log event. 538 * 539 * @param thrown a throwable (may be null) 540 */ 541 public void setThrown(Throwable thrown) { 542 this.thrown = thrown; 543 } 544 545 private static final long serialVersionUID = 5372048053134512534L; 546 547 /** 548 * @serialData Serialized fields, followed by a two byte version number 549 * (major byte, followed by minor byte), followed by information on 550 * the log record parameter array. If there is no parameter array, 551 * then -1 is written. If there is a parameter array (possible of zero 552 * length) then the array length is written as an integer, followed 553 * by String values for each parameter. If a parameter is null, then 554 * a null String is written. Otherwise the output of Object.toString() 555 * is written. 556 */ 557 private void writeObject(ObjectOutputStream out) throws IOException { 558 // We have to write serialized fields first. 559 ObjectOutputStream.PutField pf = out.putFields(); 560 pf.put("level", level); 561 pf.put("sequenceNumber", sequenceNumber); 562 pf.put("sourceClassName", sourceClassName); 563 pf.put("sourceMethodName", sourceMethodName); 564 pf.put("message", message); 565 pf.put("threadID", threadID); 566 pf.put("millis", instant.toEpochMilli()); 567 pf.put("nanoAdjustment", instant.getNano() % 1000_000); 568 pf.put("thrown", thrown); 569 pf.put("loggerName", loggerName); 570 pf.put("resourceBundleName", resourceBundleName); 571 out.writeFields(); 572 573 // Write our version number. 574 out.writeByte(1); 575 out.writeByte(0); 576 if (parameters == null) { 577 out.writeInt(-1); 578 return; 579 } 580 out.writeInt(parameters.length); 581 // Write string values for the parameters. 582 for (Object parameter : parameters) { 583 out.writeObject(Objects.toString(parameter, null)); 584 } 585 } 586 587 private void readObject(ObjectInputStream in) 588 throws IOException, ClassNotFoundException { 589 // We have to read serialized fields first. 590 ObjectInputStream.GetField gf = in.readFields(); 591 level = (Level) gf.get("level", null); 592 sequenceNumber = gf.get("sequenceNumber", 0L); 593 sourceClassName = (String) gf.get("sourceClassName", null); 594 sourceMethodName = (String) gf.get("sourceMethodName", null); 595 message = (String) gf.get("message", null); 596 threadID = gf.get("threadID", 0); 597 long millis = gf.get("millis", 0L); 598 int nanoOfMilli = gf.get("nanoAdjustment", 0); 599 instant = Instant.ofEpochSecond( 600 millis / 1000L, (millis % 1000L) * 1000_000L + nanoOfMilli); 601 thrown = (Throwable) gf.get("thrown", null); 602 loggerName = (String) gf.get("loggerName", null); 603 resourceBundleName = (String) gf.get("resourceBundleName", null); 604 605 // Read version number. 606 byte major = in.readByte(); 607 byte minor = in.readByte(); 608 if (major != 1) { 609 throw new IOException("LogRecord: bad version: " + major + "." + minor); 610 } 611 int len = in.readInt(); 612 if (len == -1) { 613 parameters = null; 614 } else { 615 parameters = new Object[len]; 616 for (int i = 0; i < parameters.length; i++) { 617 parameters[i] = in.readObject(); 618 } 619 } 620 // If necessary, try to regenerate the resource bundle. 621 if (resourceBundleName != null) { 622 try { 623 // use system class loader to ensure the ResourceBundle 624 // instance is a different instance than null loader uses 625 final ResourceBundle bundle = 626 ResourceBundle.getBundle(resourceBundleName, 627 Locale.getDefault(), 628 ClassLoader.getSystemClassLoader()); 629 resourceBundle = bundle; 630 } catch (MissingResourceException ex) { 631 // This is not a good place to throw an exception, 632 // so we simply leave the resourceBundle null. 633 resourceBundle = null; 634 } 635 } 636 637 needToInferCaller = false; 638 } 639 640 // Private method to infer the caller's class and method names 641 // 642 // Note: 643 // For testing purposes - it is possible to customize the process 644 // by which LogRecord will infer the source class name and source method name 645 // when analyzing the call stack. 646 // <p> 647 // The system property {@code jdk.logger.packages} can define a comma separated 648 // list of strings corresponding to additional package name prefixes that 649 // should be ignored when trying to infer the source caller class name. 650 // Those stack frames whose {@linkplain StackTraceElement#getClassName() 651 // declaring class name} start with one such prefix will be ignored. 652 // <p> 653 // This is primarily useful when providing utility logging classes wrapping 654 // a logger instance, as it makes it possible to instruct LogRecord to skip 655 // those utility frames when inferring the caller source class name. 656 // <p> 657 // The {@code jdk.logger.packages} system property is consulted only once. 658 // <p> 659 // This property is not standard, implementation specific, and yet 660 // undocumented (and thus subject to changes without notice). 661 // 662 private void inferCaller() { 663 needToInferCaller = false; 664 JavaLangAccess access = SharedSecrets.getJavaLangAccess(); 665 Throwable throwable = new Throwable(); 666 int depth = access.getStackTraceDepth(throwable); 667 668 boolean lookingForLogger = true; 669 for (int ix = 0; ix < depth; ix++) { 670 // Calling getStackTraceElement directly prevents the VM 671 // from paying the cost of building the entire stack frame. 672 StackTraceElement frame = 673 access.getStackTraceElement(throwable, ix); 674 String cname = frame.getClassName(); 675 boolean isLoggerImpl = isLoggerImplFrame(cname); 676 if (lookingForLogger) { 677 // Skip all frames until we have found the first logger frame. 678 if (isLoggerImpl) { 679 lookingForLogger = false; 680 } 681 } else { 682 if (!isLoggerImpl) { 683 // skip logging/logger infrastructure and reflection calls 684 if (!skipLoggingFrame(cname)) { 685 // We've found the relevant frame. 686 setSourceClassName(cname); 687 setSourceMethodName(frame.getMethodName()); 688 return; 689 } 690 } 691 } 692 } 693 // We haven't found a suitable frame, so just punt. This is 694 // OK as we are only committed to making a "best effort" here. 695 } 696 697 private boolean isLoggerImplFrame(String cname) { 698 // the log record could be created for a platform logger 699 return (cname.equals("java.util.logging.Logger") || 700 cname.startsWith("sun.util.logging.PlatformLogger")); 701 } 702 }