Improve annotations for getCause(). (#58)

This started off as a cherry-pick of
typetools/jdk@5816821.

Then I changed the annotations to JSpecify annotations.

Then found that a number of the changes in that commit appeared
questionable, so I reverted them. Specifically, for the following types,
it appears likely to me that the cause is never `null`:

- `TypeNotPresentExceptionProxy`
- `PrinterIOException`
- `MBeanException`
- `ReflectionException`
- `RuntimeErrorException`
- `RuntimeMBeanException`
- `RuntimeOperationsException`
- `JMXServerErrorException`
- `UncheckedDocletException`

Co-authored-by: Michael Ernst <mernst@cs.washington.edu>

src/java.base/share/classes/java/io/WriteAbortedException.java

@@ -25,6 +25,8 @@
 
 package java.io;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Signals that one of the ObjectStreamExceptions was thrown during a
  * write operation.  Thrown during a read operation when one of the
@@ -87,7 +89,7 @@ public String getMessage() {
      *          which may be null.
      * @since   1.4
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return detail;
     }
 }

src/java.base/share/classes/java/util/ResourceBundle.java

@@ -768,7 +768,7 @@ private void setCause(Throwable cause) {
             }
         }
 
-        private Throwable getCause() {
+        private @Nullable Throwable getCause() {
             return cause;
         }
 

src/java.base/share/classes/jdk/internal/org/xml/sax/SAXException.java

@@ -30,6 +30,8 @@
 
 package jdk.internal.org.xml.sax;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.IOException;
 import java.io.InvalidClassException;
 import java.io.ObjectInputStream;
@@ -153,7 +155,7 @@ public Exception getException ()
      *
      * @return Return the cause of the exception
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return super.getCause();
     }
 

src/java.base/share/classes/sun/util/resources/Bundles.java

@@ -40,6 +40,8 @@
 
 package sun.util.resources;
 
+import org.jspecify.annotations.Nullable;
+
 import java.lang.ref.ReferenceQueue;
 import java.lang.ref.SoftReference;
 import java.security.AccessController;
@@ -512,7 +514,7 @@ private void setCause(Throwable cause) {
             }
         }
 
-        private Throwable getCause() {
+        private @Nullable Throwable getCause() {
             return cause;
         }
 

src/java.management/share/classes/javax/management/remote/JMXProviderException.java

@@ -26,6 +26,8 @@
 
 package javax.management.remote;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.IOException;
 
 /**
@@ -70,7 +72,7 @@ public JMXProviderException(String message, Throwable cause) {
         this.cause = cause;
     }
 
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return cause;
     }
 

src/java.naming/share/classes/javax/naming/NamingException.java

@@ -25,6 +25,8 @@
 
 package javax.naming;
 
+import org.jspecify.annotations.Nullable;
+
 /**
   * This is the superclass of all exceptions thrown by
   * operations in the Context and DirContext interfaces.
@@ -356,7 +358,7 @@ public void setRootCause(Throwable e) {
       * @see #initCause(Throwable)
       * @since 1.4
       */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return getRootCause();
     }
 

src/java.rmi/share/classes/java/rmi/RemoteException.java

@@ -25,6 +25,8 @@
 
 package java.rmi;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * A {@code RemoteException} is the common superclass for a number of
  * communication-related exceptions that may occur during the execution of a
@@ -116,7 +118,7 @@ public String getMessage() {
      * @return  the cause, which may be {@code null}.
      * @since   1.4
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return detail;
     }
 }

src/java.rmi/share/classes/java/rmi/server/ServerCloneException.java

@@ -25,6 +25,8 @@
 
 package java.rmi.server;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * A {@code ServerCloneException} is thrown if a remote exception occurs
  * during the cloning of a {@code UnicastRemoteObject}.
@@ -106,7 +108,7 @@ public String getMessage() {
      * @return  the cause, which may be {@code null}.
      * @since   1.4
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return detail;
     }
 }

src/java.security.sasl/share/classes/javax/security/sasl/SaslException.java

@@ -25,6 +25,8 @@
 
 package javax.security.sasl;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.IOException;
 
 /**
@@ -90,7 +92,7 @@ public SaslException (String detail, Throwable ex) {
      * Override Throwable.getCause() to ensure deserialized object from
      * JSR 28 would return same value for getCause() (i.e., _exception).
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return _exception;
     }
 

src/java.xml.crypto/share/classes/javax/xml/crypto/KeySelectorException.java

@@ -27,6 +27,8 @@
  */
 package javax.xml.crypto;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.PrintStream;
 import java.io.PrintWriter;
 
@@ -111,7 +113,7 @@ public KeySelectorException(Throwable cause) {
      * @return the cause of this {@code KeySelectorException} or
      *         {@code null} if the cause is nonexistent or unknown.
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return cause;
     }
 

src/java.xml.crypto/share/classes/javax/xml/crypto/MarshalException.java

@@ -27,6 +27,8 @@
  */
 package javax.xml.crypto;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.PrintStream;
 import java.io.PrintWriter;
 import javax.xml.crypto.dsig.Manifest;
@@ -117,7 +119,7 @@ public MarshalException(Throwable cause) {
      * @return the cause of this {@code MarshalException} or
      *         {@code null} if the cause is nonexistent or unknown.
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return cause;
     }
 

src/java.xml.crypto/share/classes/javax/xml/crypto/NoSuchMechanismException.java

@@ -27,6 +27,8 @@
  */
 package javax.xml.crypto;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.PrintStream;
 import java.io.PrintWriter;
 import javax.xml.crypto.dsig.Manifest;
@@ -119,7 +121,7 @@ public NoSuchMechanismException(Throwable cause) {
      * @return the cause of this {@code NoSuchMechanismException} or
      *         {@code null} if the cause is nonexistent or unknown.
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return cause;
     }
 

src/java.xml.crypto/share/classes/javax/xml/crypto/URIReferenceException.java

@@ -27,6 +27,8 @@
  */
 package javax.xml.crypto;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.PrintStream;
 import java.io.PrintWriter;
 import javax.xml.crypto.dsig.keyinfo.RetrievalMethod;
@@ -151,7 +153,7 @@ public URIReference getURIReference() {
      * @return the cause of this {@code URIReferenceException} or
      *    {@code null} if the cause is nonexistent or unknown.
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return cause;
     }
 

src/java.xml.crypto/share/classes/javax/xml/crypto/dsig/TransformException.java

@@ -27,6 +27,8 @@
  */
 package javax.xml.crypto.dsig;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.PrintStream;
 import java.io.PrintWriter;
 
@@ -113,7 +115,7 @@ public TransformException(Throwable cause) {
      * @return the cause of this {@code TransformException} or
      *         {@code null} if the cause is nonexistent or unknown.
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return cause;
     }
 

src/java.xml.crypto/share/classes/javax/xml/crypto/dsig/XMLSignatureException.java

@@ -27,6 +27,8 @@
  */
 package javax.xml.crypto.dsig;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.PrintStream;
 import java.io.PrintWriter;
 
@@ -110,7 +112,7 @@ public XMLSignatureException(Throwable cause) {
      * @return the cause of this {@code XMLSignatureException} or
      *         {@code null} if the cause is nonexistent or unknown.
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return cause;
     }
 

src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMsg.java

@@ -20,6 +20,8 @@
 
 package com.sun.org.apache.xalan.internal.xsltc.compiler.util;
 
+import org.jspecify.annotations.Nullable;
+
 import com.sun.org.apache.xalan.internal.xsltc.compiler.Stylesheet;
 import com.sun.org.apache.xalan.internal.xsltc.compiler.SyntaxTreeNode;
 import java.text.MessageFormat;
@@ -247,7 +249,7 @@ public ErrorMsg(String code, Object param1, Object param2,
         _params[1] = param2;
     }
 
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return _cause;
     }
 

src/java.xml/share/classes/com/sun/org/apache/xerces/internal/xni/XNIException.java

@@ -21,6 +21,8 @@
 
 package com.sun.org.apache.xerces.internal.xni;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * This exception is the base exception of all XNI exceptions. It
  * can be constructed with an error message or used to wrap another
@@ -90,7 +92,7 @@ public Exception getException() {
         return fException;
     } // getException():Exception
 
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
        return fException;
     }
 } // class QName

src/java.xml/share/classes/javax/xml/stream/FactoryConfigurationError.java

@@ -26,6 +26,8 @@
 
 package javax.xml.stream;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * An error class for reporting factory configuration errors.
  *
@@ -97,7 +99,7 @@ public Exception getException() {
      * use the exception chaining mechanism of JDK1.4
     */
     @Override
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return nested;
     }
 

src/java.xml/share/classes/javax/xml/transform/TransformerException.java

@@ -25,6 +25,8 @@
 
 package javax.xml.transform;
 
+import org.jspecify.annotations.Nullable;
+
 import java.lang.reflect.Method;
 import java.lang.reflect.InvocationTargetException;
 import java.security.AccessControlContext;
@@ -90,7 +92,7 @@ public Throwable getException() {
      * @return the cause, or null if unknown
      */
     @Override
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
 
         return ((containedException == this)
                 ? null

src/java.xml/share/classes/javax/xml/transform/TransformerFactoryConfigurationError.java

@@ -25,6 +25,8 @@
 
 package javax.xml.transform;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Thrown when a problem with configuration with the Transformer Factories
  * exists. This error will typically be thrown when the class of a
@@ -126,7 +128,7 @@ public Exception getException() {
      * use the exception chaining mechanism of JDK1.4
     */
     @Override
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return exception;
     }
 }

src/java.xml/share/classes/javax/xml/xpath/XPathException.java

@@ -25,6 +25,8 @@
 
 package javax.xml.xpath;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.PrintWriter;
 import java.io.IOException;
 import java.io.ObjectInputStream;
@@ -94,7 +96,7 @@ public XPathException(Throwable cause) {
      *
      * @return Cause of this XPathException.
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return super.getCause();
     }
 

src/java.xml/share/classes/org/xml/sax/SAXException.java

@@ -30,6 +30,8 @@
 
 package org.xml.sax;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.IOException;
 import java.io.InvalidClassException;
 import java.io.ObjectInputStream;
@@ -153,7 +155,7 @@ public Exception getException ()
      *
      * @return Return the cause of the exception
      */
-    public Throwable getCause() {
+    public @Nullable Throwable getCause() {
         return super.getCause();
     }