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 fb85e0e Backport Javadoc improvements
fb85e0e is described below
commit fb85e0e9160dc686a1969e304968936345dd96b9
Author: Mark Thomas <[email protected]>
AuthorDate: Thu Oct 15 12:23:00 2020 +0100
Backport Javadoc improvements
---
java/javax/servlet/AsyncContext.java | 55 ++++++++++++++++++++++++++++++++-
java/javax/servlet/GenericFilter.java | 2 +-
java/javax/servlet/http/HttpFilter.java | 5 +++
java/javax/websocket/Decoder.java | 8 +++++
java/javax/websocket/Encoder.java | 8 +++++
java/javax/xml/ws/WebServiceRef.java | 2 --
java/javax/xml/ws/WebServiceRefs.java | 2 --
7 files changed, 76 insertions(+), 6 deletions(-)
diff --git a/java/javax/servlet/AsyncContext.java
b/java/javax/servlet/AsyncContext.java
index 9d0c81d..9abb6b3 100644
--- a/java/javax/servlet/AsyncContext.java
+++ b/java/javax/servlet/AsyncContext.java
@@ -17,20 +17,45 @@
package javax.servlet;
/**
- * TODO SERVLET3 - Add comments
+ * Provides the context for asynchronous request handling
+ *
* @since Servlet 3.0
*/
public interface AsyncContext {
+
+ /**
+ * The attribute name for the URI of the async request
+ */
public static final String ASYNC_REQUEST_URI =
"javax.servlet.async.request_uri";
+
+ /**
+ * The attribute name for the Context Path of the async request
+ */
public static final String ASYNC_CONTEXT_PATH =
"javax.servlet.async.context_path";
+
+ /**
+ * The attribute name for the Mapping of the async request
+ */
public static final String ASYNC_MAPPING =
"javax.servlet.async.mapping";
+
+ /**
+ * The attribute name for the Path Info of the async request
+ */
public static final String ASYNC_PATH_INFO =
"javax.servlet.async.path_info";
+
+ /**
+ * The attribute name for the Servlet Path of the async request
+ */
public static final String ASYNC_SERVLET_PATH =
"javax.servlet.async.servlet_path";
+
+ /**
+ * The attribute name for the Query String of the async request
+ */
public static final String ASYNC_QUERY_STRING =
"javax.servlet.async.query_string";
@@ -79,15 +104,43 @@ public interface AsyncContext {
*/
void dispatch(ServletContext context, String path);
+ /**
+ * Completes the async request processing and closes the response stream
+ */
void complete();
+ /**
+ * Starts a new thread to process the asynchronous request
+ *
+ * @param run a Runnable that the new thread will run
+ */
void start(Runnable run);
+ /**
+ * Adds an event listener that will be called for different AsyncEvents
fire
+ *
+ * @param listener an AsyncListener that will be called with AsyncEvent
objects
+ */
void addListener(AsyncListener listener);
+ /**
+ * Adds an event listener that will be called when different AsyncEvents
fire
+ *
+ * @param listener an AsyncListener that will be called with AsyncEvent
objects
+ * @param request the ServletRequest that will be passed with the
AsyncEvent
+ * @param response the ServletResponse that will be passed with the
AsyncEvent
+ */
void addListener(AsyncListener listener, ServletRequest request,
ServletResponse response);
+ /**
+ * Creates and returns an AsyncListener object
+ *
+ * @param <T> The type to create that extends AsyncListener
+ * @param clazz The class to instantiate to create the listener
+ * @return the newly created AsyncListener object
+ * @throws ServletException if the listener cannot be created
+ */
<T extends AsyncListener> T createListener(Class<T> clazz)
throws ServletException;
diff --git a/java/javax/servlet/GenericFilter.java
b/java/javax/servlet/GenericFilter.java
index 32ea77a..f32ac4f 100644
--- a/java/javax/servlet/GenericFilter.java
+++ b/java/javax/servlet/GenericFilter.java
@@ -20,7 +20,7 @@ import java.io.Serializable;
import java.util.Enumeration;
/**
- * Provides a base class the implements the Filter and FilterConfig interfaces
+ * Provides a base class that implements the Filter and FilterConfig interfaces
* to reduce boilerplate when writing new filters.
*
* @see javax.servlet.Filter
diff --git a/java/javax/servlet/http/HttpFilter.java
b/java/javax/servlet/http/HttpFilter.java
index 8622aeb..c2a7097 100644
--- a/java/javax/servlet/http/HttpFilter.java
+++ b/java/javax/servlet/http/HttpFilter.java
@@ -24,6 +24,11 @@ import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
+/**
+ * Provides a base class that implements the Filter interface and ensures
+ * that the Request and Response are of type HttpServletRequest and
+ * HttpServletResponse respectively.
+ */
public abstract class HttpFilter extends GenericFilter {
private static final long serialVersionUID = 1L;
diff --git a/java/javax/websocket/Decoder.java
b/java/javax/websocket/Decoder.java
index fad262e..e965583 100644
--- a/java/javax/websocket/Decoder.java
+++ b/java/javax/websocket/Decoder.java
@@ -23,8 +23,16 @@ import java.nio.ByteBuffer;
public interface Decoder {
+ /**
+ * Initialise the decoder.
+ *
+ * @param endpointConfig The end-point configuration
+ */
abstract void init(EndpointConfig endpointConfig);
+ /**
+ * Destroy the decoder.
+ */
abstract void destroy();
interface Binary<T> extends Decoder {
diff --git a/java/javax/websocket/Encoder.java
b/java/javax/websocket/Encoder.java
index 42a107f..f69ddd9 100644
--- a/java/javax/websocket/Encoder.java
+++ b/java/javax/websocket/Encoder.java
@@ -23,8 +23,16 @@ import java.nio.ByteBuffer;
public interface Encoder {
+ /**
+ * Initialise the encoder.
+ *
+ * @param endpointConfig The end-point configuration
+ */
abstract void init(EndpointConfig endpointConfig);
+ /**
+ * Destroy the decoder.
+ */
abstract void destroy();
interface Text<T> extends Encoder {
diff --git a/java/javax/xml/ws/WebServiceRef.java
b/java/javax/xml/ws/WebServiceRef.java
index 28b150e..22ae41e 100644
--- a/java/javax/xml/ws/WebServiceRef.java
+++ b/java/javax/xml/ws/WebServiceRef.java
@@ -14,8 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
-
package javax.xml.ws;
import java.lang.annotation.ElementType;
diff --git a/java/javax/xml/ws/WebServiceRefs.java
b/java/javax/xml/ws/WebServiceRefs.java
index e4f428c..fad693b 100644
--- a/java/javax/xml/ws/WebServiceRefs.java
+++ b/java/javax/xml/ws/WebServiceRefs.java
@@ -14,8 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
-
package javax.xml.ws;
import java.lang.annotation.ElementType;
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
