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