This is an automated email from the ASF dual-hosted git repository.

markt pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git


The following commit(s) were added to refs/heads/9.0.x by this push:
     new 025522f  Chip away at the Javadoc warnings with Java 17
025522f is described below

commit 025522fcba0a6d4a48ac1f85a154936825445a84
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Mon Jul 26 15:33:29 2021 +0100

    Chip away at the Javadoc warnings with Java 17
---
 java/javax/servlet/AsyncEvent.java                 | 53 +++++++++++++++++++++-
 java/javax/servlet/AsyncListener.java              | 44 +++++++++++++++++-
 java/javax/servlet/DispatcherType.java             | 26 +++++++++++
 .../javax/servlet/HttpMethodConstraintElement.java | 23 +++++++++-
 4 files changed, 143 insertions(+), 3 deletions(-)

diff --git a/java/javax/servlet/AsyncEvent.java 
b/java/javax/servlet/AsyncEvent.java
index 4b0f0b3..5006bc0 100644
--- a/java/javax/servlet/AsyncEvent.java
+++ b/java/javax/servlet/AsyncEvent.java
@@ -17,7 +17,8 @@
 package javax.servlet;
 
 /**
- * TODO SERVLET3 - Add comments
+ * Used to pass data to the methods of {@link AsyncListener}.
+ *
  * @since Servlet 3.0
  */
 public class AsyncEvent {
@@ -26,6 +27,11 @@ public class AsyncEvent {
     private final ServletResponse response;
     private final Throwable throwable;
 
+    /**
+     * Creates an instance using the provide parameters.
+     *
+     * @param context   The asynchronous context associated with the event
+     */
     public AsyncEvent(AsyncContext context) {
         this.context = context;
         this.request = null;
@@ -33,6 +39,13 @@ public class AsyncEvent {
         this.throwable = null;
     }
 
+    /**
+     * Creates an instance using the provide parameters.
+     *
+     * @param context   The asynchronous context associated with the event
+     * @param request   The request associated with the event
+     * @param response  The response associated with the event
+     */
     public AsyncEvent(AsyncContext context, ServletRequest request,
             ServletResponse response) {
         this.context = context;
@@ -41,6 +54,12 @@ public class AsyncEvent {
         this.throwable = null;
     }
 
+    /**
+     * Creates an instance using the provide parameters.
+     *
+     * @param context   The asynchronous context associated with the event
+     * @param throwable The throwable associated with the event
+     */
     public AsyncEvent(AsyncContext context, Throwable throwable) {
         this.context = context;
         this.throwable = throwable;
@@ -48,6 +67,14 @@ public class AsyncEvent {
         this.response = null;
     }
 
+    /**
+     * Creates an instance using the provide parameters.
+     *
+     * @param context   The asynchronous context associated with the event
+     * @param request   The request associated with the event
+     * @param response  The response associated with the event
+     * @param throwable The throwable associated with the event
+     */
     public AsyncEvent(AsyncContext context, ServletRequest request,
             ServletResponse response, Throwable throwable) {
         this.context = context;
@@ -56,18 +83,42 @@ public class AsyncEvent {
         this.throwable = throwable;
     }
 
+    /**
+     * Obtain the asynchronous context associated with the event.
+     *
+     * @return  The asynchronous context associated with the event or
+     *          {@code null} if one was not specified
+     */
     public AsyncContext getAsyncContext() {
         return context;
     }
 
+    /**
+     * Obtain the request associated with the event.
+     *
+     * @return  The request associated with the event or
+     *          {@code null} if one was not specified
+     */
     public ServletRequest getSuppliedRequest() {
         return request;
     }
 
+    /**
+     * Obtain the response associated with the event.
+     *
+     * @return  The response associated with the event or
+     *          {@code null} if one was not specified
+     */
     public ServletResponse getSuppliedResponse() {
         return response;
     }
 
+    /**
+     * Obtain the throwable associated with the event.
+     *
+     * @return  The throwable associated with the event or
+     *          {@code null} if one was not specified
+     */
     public Throwable getThrowable() {
         return throwable;
     }
diff --git a/java/javax/servlet/AsyncListener.java 
b/java/javax/servlet/AsyncListener.java
index 66f6392..ddd24d4 100644
--- a/java/javax/servlet/AsyncListener.java
+++ b/java/javax/servlet/AsyncListener.java
@@ -20,12 +20,54 @@ import java.io.IOException;
 import java.util.EventListener;
 
 /**
- * TODO SERVLET3 - Add comments
+ * Listener for events associated with an {@link AsyncContext}.
+ *
  * @since Servlet 3.0
  */
 public interface AsyncListener extends EventListener {
+
+    /**
+     * This event is fired after the call to {@link AsyncContext#complete()}
+     * has been processed by the container.
+     *
+     * @param event Provides access to the objects associated with the event
+     *
+     * @throws IOException Should be thrown if an I/O error occurs during the
+     *                     processing of the event
+     */
     void onComplete(AsyncEvent event) throws IOException;
+
+    /**
+     * This event is fired if an asynchronous operation times out but before
+     * the container takes any action as a result of the timeout.
+     *
+     * @param event Provides access to the objects associated with the event
+     *
+     * @throws IOException Should be thrown if an I/O error occurs during the
+     *                     processing of the event
+     */
     void onTimeout(AsyncEvent event) throws IOException;
+
+    /**
+     * This event is fired if an error occurs during an asynchronous operation
+     * but before the container takes any action as a result of the error.
+     *
+     * @param event Provides access to the objects associated with the event
+     *
+     * @throws IOException Should be thrown if an I/O error occurs during the
+     *                     processing of the event
+     */
     void onError(AsyncEvent event) throws IOException;
+
+    /**
+     * This event is fired if new call is made to
+     * {@link ServletRequest#startAsync()} after the completion of the
+     * {@link AsyncContext} to which this listener was added.
+     *
+     * @param event Provides access to the objects associated with the event
+     *
+     * @throws IOException Should be thrown if an I/O error occurs during the
+     *                     processing of the event
+     */
     void onStartAsync(AsyncEvent event) throws IOException;
 }
diff --git a/java/javax/servlet/DispatcherType.java 
b/java/javax/servlet/DispatcherType.java
index 67e5603..a15b9fa 100644
--- a/java/javax/servlet/DispatcherType.java
+++ b/java/javax/servlet/DispatcherType.java
@@ -17,12 +17,38 @@
 package javax.servlet;
 
 /**
+ * Enumeration of dispatcher types. Used both to define filter mappings and by
+ * Servlets to determine why they were called.
+ *
  * @since Servlet 3.0
  */
 public enum DispatcherType {
+
+    /**
+     * {@link RequestDispatcher#forward(ServletRequest, ServletResponse)}
+     */
     FORWARD,
+
+    /**
+     * {@link RequestDispatcher#include(ServletRequest, ServletResponse)}
+     */
     INCLUDE,
+
+    /**
+     * Normal (non-dispatched) requests.
+     */
     REQUEST,
+
+    /**
+     * {@link AsyncContext#dispatch()}, {@link AsyncContext#dispatch(String)}
+     * and
+     * {@link AsyncContext#addListener(AsyncListener, ServletRequest, 
ServletResponse)}
+     */
     ASYNC,
+
+    /**
+     * When the container has passed processing to the error handler mechanism
+     * such as a defined error page.
+     */
     ERROR
 }
diff --git a/java/javax/servlet/HttpMethodConstraintElement.java 
b/java/javax/servlet/HttpMethodConstraintElement.java
index 5de2ad9..941db86 100644
--- a/java/javax/servlet/HttpMethodConstraintElement.java
+++ b/java/javax/servlet/HttpMethodConstraintElement.java
@@ -19,8 +19,10 @@ package javax.servlet;
 import java.util.ResourceBundle;
 
 /**
+ * Programmatic equivalent of a security constraint defined for a single HTTP
+ * method.
+ *
  * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
  */
 public class HttpMethodConstraintElement extends HttpConstraintElement {
 
@@ -31,6 +33,12 @@ public class HttpMethodConstraintElement extends 
HttpConstraintElement {
 
     private final String methodName;
 
+    /**
+     * Construct an instance for the given HTTP method name and a default
+     * {@link HttpConstraintElement}.
+     *
+     * @param methodName    The HTTP method name
+     */
     public HttpMethodConstraintElement(String methodName) {
         if (methodName == null || methodName.length() == 0) {
             throw new IllegalArgumentException(lStrings.getString(
@@ -39,6 +47,13 @@ public class HttpMethodConstraintElement extends 
HttpConstraintElement {
         this.methodName = methodName;
     }
 
+    /**
+     * Construct an instance for the given HTTP method name and
+     * {@link HttpConstraintElement}.
+     *
+     * @param methodName    The HTTP method name
+     * @param constraint    The constraint for the given method
+     */
     public HttpMethodConstraintElement(String methodName,
             HttpConstraintElement constraint) {
         super(constraint.getEmptyRoleSemantic(),
@@ -51,6 +66,12 @@ public class HttpMethodConstraintElement extends 
HttpConstraintElement {
         this.methodName = methodName;
     }
 
+    /**
+     * Obtain the name of the HTTP method for which this constraint was
+     * created.
+     *
+     * @return  The HTTP method name as provided to the constructor
+     */
     public String getMethodName() {
         return methodName;
     }

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org

Reply via email to