You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2021/07/26 14:35:10 UTC
[tomcat] branch 9.0.x updated: Chip away at the Javadoc warnings
with Java 17
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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org