Add nullability annotation based on JavaDoc

api/pom.xml

@@ -90,6 +90,11 @@
     </properties>
 
     <dependencies>
+        <dependency>
+            <groupId>jakarta.annotation</groupId>
+            <artifactId>jakarta.annotation-api</artifactId>
+            <version>2.1.1</version>
+        </dependency>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter-engine</artifactId>

api/src/main/java/jakarta/servlet/AsyncEvent.java

@@ -17,6 +17,8 @@
 
 package jakarta.servlet;
 
+import jakarta.annotation.Nullable;
+
 /**
  * Event that gets fired when the asynchronous operation initiated on a ServletRequest (via a call to
  * {@link ServletRequest#startAsync} or {@link ServletRequest#startAsync(ServletRequest, ServletResponse)}) has
@@ -29,6 +31,7 @@ public class AsyncEvent {
     private final AsyncContext context;
     private final ServletRequest request;
     private final ServletResponse response;
+    @Nullable
     private final Throwable throwable;
 
     /**
@@ -69,7 +72,7 @@ public AsyncEvent(AsyncContext context, Throwable throwable) {
      * @param response the ServletResponse to be delivered with this AsyncEvent
      * @param throwable the Throwable to be delivered with this AsyncEvent
      */
-    public AsyncEvent(AsyncContext context, ServletRequest request, ServletResponse response, Throwable throwable) {
+    public AsyncEvent(AsyncContext context, ServletRequest request, ServletResponse response, @Nullable Throwable throwable) {
         this.context = context;
         this.request = request;
         this.response = response;
@@ -97,6 +100,7 @@ public AsyncContext getAsyncContext() {
      * @return the ServletRequest that was used to initialize this AsyncEvent, or null if this AsyncEvent was initialized
      * without any ServletRequest
      */
+    @Nullable
     public ServletRequest getSuppliedRequest() {
         return request;
     }
@@ -113,6 +117,7 @@ public ServletRequest getSuppliedRequest() {
      * @return the ServletResponse that was used to initialize this AsyncEvent, or null if this AsyncEvent was initialized
      * without any ServletResponse
      */
+    @Nullable
     public ServletResponse getSuppliedResponse() {
         return response;
     }
@@ -123,6 +128,7 @@ public ServletResponse getSuppliedResponse() {
      * @return the Throwable that was used to initialize this AsyncEvent, or null if this AsyncEvent was initialized without
      * any Throwable
      */
+    @Nullable
     public Throwable getThrowable() {
         return throwable;
     }

api/src/main/java/jakarta/servlet/FilterConfig.java

@@ -18,6 +18,7 @@
 
 package jakarta.servlet;
 
+import jakarta.annotation.Nullable;
 import java.util.Enumeration;
 
 /**
@@ -53,6 +54,7 @@ public interface FilterConfig {
      * @return a <code>String</code> containing the value of the initialization parameter, or <code>null</code> if the
      * initialization parameter does not exist
      */
+    @Nullable
     String getInitParameter(String name);
 
     /**

api/src/main/java/jakarta/servlet/FilterRegistration.java

@@ -17,7 +17,9 @@
 
 package jakarta.servlet;
 
-import java.util.*;
+import jakarta.annotation.Nullable;
+import java.util.Collection;
+import java.util.EnumSet;
 
 /**
  * Interface through which a {@link Filter} may be further configured.
@@ -51,8 +53,9 @@ public interface FilterRegistration extends Registration {
      * @throws IllegalStateException if the ServletContext from which this FilterRegistration was obtained has already been
      * initialized
      */
-    void addMappingForServletNames(EnumSet<DispatcherType> dispatcherTypes, boolean isMatchAfter,
-            String... servletNames);
+    void addMappingForServletNames(
+        @Nullable EnumSet<DispatcherType> dispatcherTypes, boolean isMatchAfter, String... servletNames
+    );
 
     /**
      * Gets the currently available servlet name mappings of the Filter represented by this <code>FilterRegistration</code>.
@@ -91,8 +94,9 @@ void addMappingForServletNames(EnumSet<DispatcherType> dispatcherTypes, boolean
      * @throws IllegalStateException if the ServletContext from which this FilterRegistration was obtained has already been
      * initialized
      */
-    void addMappingForUrlPatterns(EnumSet<DispatcherType> dispatcherTypes, boolean isMatchAfter,
-            String... urlPatterns);
+    void addMappingForUrlPatterns(
+        @Nullable EnumSet<DispatcherType> dispatcherTypes, boolean isMatchAfter, String... urlPatterns
+    );
 
     /**
      * Gets the currently available URL pattern mappings of the Filter represented by this <code>FilterRegistration</code>.

api/src/main/java/jakarta/servlet/GenericFilter.java

@@ -17,6 +17,7 @@
 
 package jakarta.servlet;
 
+import jakarta.annotation.Nullable;
 import java.util.Enumeration;
 import java.util.ResourceBundle;
 
@@ -49,6 +50,7 @@ public abstract class GenericFilter implements Filter, FilterConfig, java.io.Ser
     private static final String LSTRING_FILE = "jakarta.servlet.LocalStrings";
     private static final ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE);
 
+    @Nullable
     private transient FilterConfig config;
 
     /**
@@ -79,6 +81,7 @@ public GenericFilter() {
      * @since Servlet 4.0
      *
      */
+    @Nullable
     @Override
     public String getInitParameter(String name) {
         FilterConfig fc = getFilterConfig();
@@ -117,13 +120,14 @@ public Enumeration<String> getInitParameterNames() {
 
     /**
      * <p>
-     * Returns this servlet's {@link ServletConfig} object.
+     * Returns this servlet's {@link ServletConfig} object, or null if it has not been initialized.
      * </p>
      *
      * @return FilterConfig the <code>FilterConfig</code> object that initialized this filter
      *
      * @since Servlet 4.0
      */
+    @Nullable
     public FilterConfig getFilterConfig() {
         return config;
     }

api/src/main/java/jakarta/servlet/GenericServlet.java

@@ -18,6 +18,7 @@
 
 package jakarta.servlet;
 
+import jakarta.annotation.Nullable;
 import java.io.IOException;
 import java.util.Enumeration;
 import java.util.ResourceBundle;
@@ -50,6 +51,7 @@ public abstract class GenericServlet implements Servlet, ServletConfig, java.io.
     private static final String LSTRING_FILE = "jakarta.servlet.LocalStrings";
     private static final ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE);
 
+    @Nullable
     private transient ServletConfig config;
 
     /**
@@ -83,6 +85,7 @@ public void destroy() {
      * @return String a <code>String</code> containing the value of the initialization parameter
      *
      */
+    @Nullable
     @Override
     public String getInitParameter(String name) {
         ServletConfig sc = getServletConfig();
@@ -117,10 +120,11 @@ public Enumeration<String> getInitParameterNames() {
     }
 
     /**
-     * Returns this servlet's {@link ServletConfig} object.
+     * Returns this servlet's {@link ServletConfig} object, or <code>null</code> if it has not been initialized.
      *
      * @return ServletConfig the <code>ServletConfig</code> object that initialized this servlet
      */
+    @Nullable
     @Override
     public ServletConfig getServletConfig() {
         return config;

api/src/main/java/jakarta/servlet/HttpMethodConstraintElement.java

@@ -17,6 +17,7 @@
 
 package jakarta.servlet;
 
+import jakarta.annotation.Nonnull;
 import jakarta.servlet.annotation.HttpMethodConstraint;
 
 /**
@@ -34,7 +35,7 @@ public class HttpMethodConstraintElement extends HttpConstraintElement {
      * @param methodName the name of an HTTP protocol method. The name must not be null, or the empty string, and must be a
      * legitimate HTTP Method name as defined by RFC 7231
      */
-    public HttpMethodConstraintElement(String methodName) {
+    public HttpMethodConstraintElement(@Nonnull String methodName) {
         if (methodName == null || methodName.length() == 0) {
             throw new IllegalArgumentException("invalid HTTP method name");
         }
@@ -49,7 +50,7 @@ public HttpMethodConstraintElement(String methodName) {
      *
      * @param constraint the HTTPconstraintElement value to assign to the named HTTP method
      */
-    public HttpMethodConstraintElement(String methodName, HttpConstraintElement constraint) {
+    public HttpMethodConstraintElement(@Nonnull String methodName, HttpConstraintElement constraint) {
         super(constraint.getEmptyRoleSemantic(), constraint.getTransportGuarantee(), constraint.getRolesAllowed());
         if (methodName == null || methodName.length() == 0) {
             throw new IllegalArgumentException("invalid HTTP method name");

api/src/main/java/jakarta/servlet/MultipartConfigElement.java

@@ -17,6 +17,7 @@
 
 package jakarta.servlet;
 
+import jakarta.annotation.Nullable;
 import jakarta.servlet.annotation.MultipartConfig;
 
 /**
@@ -36,7 +37,7 @@ public class MultipartConfigElement {
      *
      * @param location defaults to "" if values is null.
      */
-    public MultipartConfigElement(String location) {
+    public MultipartConfigElement(@Nullable String location) {
         if (location == null) {
             this.location = "";
         } else {
@@ -55,7 +56,7 @@ public MultipartConfigElement(String location) {
      * @param maxRequestSize the maximum size allowed (in bytes) for multipart/form-data requests
      * @param fileSizeThreshold the size threshold (in bytes) after which files will be written to disk
      */
-    public MultipartConfigElement(String location, long maxFileSize, long maxRequestSize, int fileSizeThreshold) {
+    public MultipartConfigElement(@Nullable String location, long maxFileSize, long maxRequestSize, int fileSizeThreshold) {
         if (location == null) {
             this.location = "";
         } else {

api/src/main/java/jakarta/servlet/Registration.java

@@ -17,6 +17,7 @@
 
 package jakarta.servlet;
 
+import jakarta.annotation.Nullable;
 import java.util.Map;
 import java.util.Set;
 
@@ -50,6 +51,7 @@ public interface Registration {
      * @return the fully qualified class name of the Servlet or Filter that is represented by this Registration, or null if
      * this Registration is preliminary
      */
+    @Nullable
     String getClassName();
 
     /**
@@ -77,6 +79,7 @@ public interface Registration {
      * @return the value of the initialization parameter with the given name, or <tt>null</tt> if no initialization
      * parameter with the given name exists
      */
+    @Nullable
     String getInitParameter(String name);
 
     /**

api/src/main/java/jakarta/servlet/ServletConfig.java

@@ -18,6 +18,7 @@
 
 package jakarta.servlet;
 
+import jakarta.annotation.Nullable;
 import java.util.Enumeration;
 
 /**
@@ -51,6 +52,7 @@ public interface ServletConfig {
      * @return a <code>String</code> containing the value of the initialization parameter, or <code>null</code> if the
      * initialization parameter does not exist
      */
+    @Nullable
     String getInitParameter(String name);
 
     /**

api/src/main/java/jakarta/servlet/ServletContainerInitializer.java

@@ -17,6 +17,7 @@
 
 package jakarta.servlet;
 
+import jakarta.annotation.Nullable;
 import java.util.Set;
 
 /**
@@ -74,5 +75,5 @@ public interface ServletContainerInitializer {
      *
      * @throws ServletException if an error has occurred
      */
-    void onStartup(Set<Class<?>> c, ServletContext ctx) throws ServletException;
+    void onStartup(@Nullable Set<Class<?>> c, ServletContext ctx) throws ServletException;
 }