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 <ma...@apache.org> 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: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org