Add nullability annotation based on JavaDoc

Signed-off-by Dennis Neufeld [email protected]

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,8 @@ 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 +93,8 @@ 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;
 }