1 /*
2 * Copyright (c) 1994, 2019, 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.lang;
27
28 /**
29 * Thrown when an application attempts to use {@code null} in a
30 * case where an object is required. These include:
31 * <ul>
32 * <li>Calling the instance method of a {@code null} object.
33 * <li>Accessing or modifying the field of a {@code null} object.
34 * <li>Taking the length of {@code null} as if it were an array.
35 * <li>Accessing or modifying the slots of {@code null} as if it
36 * were an array.
37 * <li>Throwing {@code null} as if it were a {@code Throwable}
38 * value.
39 * </ul>
40 * <p>
41 * Applications should throw instances of this class to indicate
42 * other illegal uses of the {@code null} object.
43 *
44 * {@code NullPointerException} objects may be constructed by the
45 * virtual machine as if {@linkplain Throwable#Throwable(String,
46 * Throwable, boolean, boolean) suppression were disabled and/or the
47 * stack trace was not writable}.
48 *
49 * @author unascribed
50 * @since 1.0
51 */
52 public class NullPointerException extends RuntimeException {
53 @java.io.Serial
54 private static final long serialVersionUID = 5162710183389028792L;
55
56 /**
57 * Constructs a {@code NullPointerException} with no detail message.
58 */
59 public NullPointerException() {
60 super();
61 }
62
63 /**
64 * Constructs a {@code NullPointerException} with the specified
65 * detail message.
66 *
67 * @param s the detail message.
68 */
69 public NullPointerException(String s) {
70 super(s);
71 }
72
73 private static final String MUST_COMPUTE_EXTENDED_MESSAGE =
74 "MUST_COMPUTE_EXTENDED_MESSAGE";
75 private static final String NO_EXTENDED_MESSAGE =
76 "NO_EXTENDED_MESSAGE";
77 private transient String extendedMessage;
78
79 /**
80 * {@inheritDoc}
81 */
82 public synchronized Throwable fillInStackTrace() {
83 // After the stack trace is changed the extended NPE algorithm
84 // will compute a wrong message. So compute it beforehand.
85 if (extendedMessage == null) {
86 // The first call. Don't compute the message, we'll
87 // do it lazily.
88 extendedMessage = MUST_COMPUTE_EXTENDED_MESSAGE;
89 } else if (extendedMessage == MUST_COMPUTE_EXTENDED_MESSAGE) {
90 // The second call.
91 extendedMessage = getExtendedNPEMessage();
92 }
93 return super.fillInStackTrace();
94 }
95
96 /**
97 * Returns the detail message string of this throwable.
98 *
99 * <p> If a non-null message was supplied in a constructor it is
100 * returned. Otherwise, an implementation specific message or
101 * {@code null} is returned.
102 *
103 * @implNote
104 * If no explicit message was passed to the constructor, and as
105 * long as certain internal information is available, a verbose
106 * description of the null reference is returned.
107 * The internal information is not available in deserialized
108 * NullPointerExceptions.
109 *
110 * @return the detail message string, which may be {@code null}.
111 */
112 public String getMessage() {
113 String message = super.getMessage();
114 if (message == null) {
115 synchronized(this) {
116 if (extendedMessage == MUST_COMPUTE_EXTENDED_MESSAGE) {
117 // Only the original stack trace was filled in. Message will
118 // compute correctly.
119 extendedMessage = getExtendedNPEMessage();
120 }
121 if (extendedMessage != NO_EXTENDED_MESSAGE) {
122 return extendedMessage;
123 }
124 }
125 }
126 return message;
127 }
128
129 /**
130 * Get an extended exception message. This returns a string describing
131 * the location and cause of the exception. It returns NO_EXTENDED_MESSAGE for
132 * exceptions where this is not applicable.
133 */
134 private String getExtendedNPEMessage() {
135 String msg = getExtendedNPEMessage0();
136 if (msg == null) return NO_EXTENDED_MESSAGE;
137 return msg;
138 }
139
140 private native String getExtendedNPEMessage0();
141 }