This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 8.5.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/8.5.x by this push:
new 29a4bbf4fc Align with 9.0.x
29a4bbf4fc is described below
commit 29a4bbf4fcb72b699f776cfcc926ed5f2902de0d
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Fri Apr 14 14:45:34 2023 +0100
Align with 9.0.x
More Javadoc improvements
Schema comment fixes
---
java/javax/servlet/AsyncContext.java | 4 ++-
java/javax/servlet/Servlet.java | 2 +-
java/javax/servlet/ServletRequest.java | 7 ++---
java/javax/servlet/http/HttpServletResponse.java | 30 +++++++++++++++-------
.../servlet/http/HttpServletResponseWrapper.java | 2 +-
java/javax/servlet/jsp/JspPage.java | 15 +++++++----
java/javax/servlet/jsp/tagext/IterationTag.java | 1 -
java/javax/servlet/jsp/tagext/VariableInfo.java | 4 +--
java/javax/servlet/resources/jsp_2_1.xsd | 2 +-
.../servlet/resources/web-jsptaglibrary_1_1.dtd | 2 +-
.../servlet/resources/web-jsptaglibrary_1_2.dtd | 2 +-
.../servlet/resources/web-jsptaglibrary_2_0.xsd | 2 +-
.../servlet/resources/web-jsptaglibrary_2_1.xsd | 2 +-
java/javax/websocket/Decoder.java | 8 ++++++
java/javax/websocket/Encoder.java | 8 ++++++
15 files changed, 63 insertions(+), 28 deletions(-)
diff --git a/java/javax/servlet/AsyncContext.java
b/java/javax/servlet/AsyncContext.java
index b74ef2c407..57e336a4d5 100644
--- a/java/javax/servlet/AsyncContext.java
+++ b/java/javax/servlet/AsyncContext.java
@@ -17,7 +17,9 @@
package javax.servlet;
/**
- * TODO SERVLET3 - Add comments
+ * Provides the context for asynchronous request handling
+ *
+ * @since Servlet 3.0
*/
public interface AsyncContext {
diff --git a/java/javax/servlet/Servlet.java b/java/javax/servlet/Servlet.java
index f326681147..2ae5ede385 100644
--- a/java/javax/servlet/Servlet.java
+++ b/java/javax/servlet/Servlet.java
@@ -90,7 +90,7 @@ public interface Servlet {
* Servlets typically run inside multithreaded servlet containers that can
handle multiple requests concurrently.
* Developers must be aware to synchronize access to any shared resources
such as files, network connections, and as
* well as the servlet's class and instance variables. More information on
multithreaded programming in Java is
- * available in <a href
="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html";> the
Java tutorial on
+ * available in <a
href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html";> the
Java tutorial on
* multi-threaded programming</a>.
*
* @param req the <code>ServletRequest</code> object that contains the
client's request
diff --git a/java/javax/servlet/ServletRequest.java
b/java/javax/servlet/ServletRequest.java
index b3fcff596d..bf59351afc 100644
--- a/java/javax/servlet/ServletRequest.java
+++ b/java/javax/servlet/ServletRequest.java
@@ -18,6 +18,7 @@ package javax.servlet;
import java.io.BufferedReader;
import java.io.IOException;
+import java.io.UnsupportedEncodingException;
import java.util.Enumeration;
import java.util.Locale;
import java.util.Map;
@@ -77,11 +78,11 @@ public interface ServletRequest {
* Overrides the name of the character encoding used in the body of this
request. This method must be called prior
* to reading request parameters or reading input using getReader().
*
- * @param env a <code>String</code> containing the name of the character
encoding.
+ * @param encoding a {@code String} containing the name of the character
encoding
*
- * @throws java.io.UnsupportedEncodingException if this is not a valid
encoding
+ * @throws UnsupportedEncodingException if this is not a valid encoding
*/
- void setCharacterEncoding(String env) throws
java.io.UnsupportedEncodingException;
+ void setCharacterEncoding(String encoding) throws
UnsupportedEncodingException;
/**
* Returns the length, in bytes, of the request body and made available by
the input stream, or -1 if the length is
diff --git a/java/javax/servlet/http/HttpServletResponse.java
b/java/javax/servlet/http/HttpServletResponse.java
index 54e2bf801f..c6cdec158f 100644
--- a/java/javax/servlet/http/HttpServletResponse.java
+++ b/java/javax/servlet/http/HttpServletResponse.java
@@ -133,20 +133,32 @@ public interface HttpServletResponse extends
ServletResponse {
void sendError(int sc) throws IOException;
/**
- * Sends a temporary redirect response to the client using the specified
redirect location URL. This method can
- * accept relative URLs; the servlet container must convert the relative
URL to an absolute URL before sending the
- * response to the client. If the location is relative without a leading
'/' the container interprets it as relative
- * to the current request URI. If the location is relative with a leading
'/' the container interprets it as
- * relative to the servlet container root.
+ * Sends a redirect response to the client using the specified redirect
location URL with the status code
+ * {@link #SC_FOUND} 302 (Found), clears the response buffer and commits
the response. The response buffer will be
+ * replaced with a short hypertext note as per RFC 9110.
+ * <p>
+ * This method has no effect if called from an include.
+ * <p>
+ * This method accepts both relative and absolute URLs. Absolute URLs
passed to this method are used as provided as
+ * the redirect location URL. Relative URLs are converted to absolute
URLs. If converting a relative URL to an absolute URL then:
+ * <ul>
+ * <li>If the location is relative without a leading '/' the container
interprets it as relative to the current
+ * request URI.</li>
+ * <li>If the location is relative with a leading '/' the container
interprets it as relative to the servlet
+ * container root.</li>
+ * <li>If the location is relative with two leading '/' the container
interprets it as a network-path reference (see
+ * <a href="http://www.ietf.org/rfc/rfc3986.txt";> RFC 3986: Uniform
Resource Identifier (URI): Generic Syntax</a>,
+ * section 4.2 "Relative Reference").</li>
+ * </ul>
* <p>
* If the response has already been committed, this method throws an
IllegalStateException. After using this method,
* the response should be considered to be committed and should not be
written to.
*
- * @param location the redirect location URL
+ * @param location the redirect location URL (may be absolute or relative)
*
- * @exception IOException If an input or output exception occurs
- * @exception IllegalStateException If the response was committed or if a
partial URL is given and cannot be
- * converted into a valid URL
+ * @exception IOException If an input or output exception
occurs
+ * @exception IllegalArgumentException If a relative URL is given and
cannot be converted into an absolute URL
+ * @exception IllegalStateException If the response was already
committed when this method was called
*/
void sendRedirect(String location) throws IOException;
diff --git a/java/javax/servlet/http/HttpServletResponseWrapper.java
b/java/javax/servlet/http/HttpServletResponseWrapper.java
index 41c7cb047a..6de0e06f50 100644
--- a/java/javax/servlet/http/HttpServletResponseWrapper.java
+++ b/java/javax/servlet/http/HttpServletResponseWrapper.java
@@ -120,7 +120,7 @@ public class HttpServletResponseWrapper extends
ServletResponseWrapper implement
}
/**
- * The default behavior of this method is to return sendRedirect(String
location) on the wrapped response object.
+ * The default behavior of this method is to call sendRedirect(String
location) on the wrapped response object.
*/
@Override
public void sendRedirect(String location) throws IOException {
diff --git a/java/javax/servlet/jsp/JspPage.java
b/java/javax/servlet/jsp/JspPage.java
index e9f10f8805..af7b1a952a 100644
--- a/java/javax/servlet/jsp/JspPage.java
+++ b/java/javax/servlet/jsp/JspPage.java
@@ -58,15 +58,20 @@ public interface JspPage extends Servlet {
/**
* The jspInit() method is invoked when the JSP page is initialized. It is
the responsibility of the JSP
* implementation (and of the class mentioned by the extends attribute, if
present) that at this point invocations
- * to the getServletConfig() method will return the desired value. A JSP
page can override this method by including
- * a definition for it in a declaration element. A JSP page should
redefine the init() method from Servlet.
+ * to the getServletConfig() method will return the desired value.
+ * <p>
+ * A JSP page can override this method by including a definition for it in
a declaration element.
+ * <p>
+ * A JSP page should redefine the init() method from Servlet.
*/
void jspInit();
/**
- * The jspDestroy() method is invoked when the JSP page is about to be
destroyed. A JSP page can override this
- * method by including a definition for it in a declaration element. A JSP
page should redefine the destroy() method
- * from Servlet.
+ * The jspDestroy() method is invoked when the JSP page is about to be
destroyed.
+ * <p>
+ * A JSP page can override this method by including a definition for it in
a declaration element.
+ * <p>
+ * A JSP page should redefine the destroy() method from Servlet.
*/
void jspDestroy();
diff --git a/java/javax/servlet/jsp/tagext/IterationTag.java
b/java/javax/servlet/jsp/tagext/IterationTag.java
index 04a82174f7..2ddb752cd3 100644
--- a/java/javax/servlet/jsp/tagext/IterationTag.java
+++ b/java/javax/servlet/jsp/tagext/IterationTag.java
@@ -61,7 +61,6 @@ public interface IterationTag extends Tag {
* Request the reevaluation of some body. Returned from doAfterBody. For
compatibility with JSP 1.1, the value is
* carefully selected to be the same as the, now deprecated,
BodyTag.EVAL_BODY_TAG,
*/
-
int EVAL_BODY_AGAIN = 2;
/**
diff --git a/java/javax/servlet/jsp/tagext/VariableInfo.java
b/java/javax/servlet/jsp/tagext/VariableInfo.java
index 655ba366e5..c958e2a9e5 100644
--- a/java/javax/servlet/jsp/tagext/VariableInfo.java
+++ b/java/javax/servlet/jsp/tagext/VariableInfo.java
@@ -41,8 +41,8 @@ package javax.servlet.jsp.tagext;
* <p>
* Frequently a fully qualified class name will refer to a class that is known
to the tag library and thus, delivered in
* the same JAR file as the tag handlers. In most other remaining cases it
will refer to a class that is in the platform
- * on which the JSP processor is built (like J2EE). Using fully qualified
class names in this manner makes the usage
- * relatively resistant to configuration errors.
+ * on which the JSP processor is built. Using fully qualified class names in
this manner makes the usage relatively
+ * resistant to configuration errors.
* <p>
* A short name is usually generated by the tag library based on some
attributes passed through from the custom action
* user (the author), and it is thus less robust: for instance a missing
import directive in the referring JSP page will
diff --git a/java/javax/servlet/resources/jsp_2_1.xsd
b/java/javax/servlet/resources/jsp_2_1.xsd
index 1c5c372c19..e58edba331 100644
--- a/java/javax/servlet/resources/jsp_2_1.xsd
+++ b/java/javax/servlet/resources/jsp_2_1.xsd
@@ -20,7 +20,7 @@
<!--
** The actual Sun XSD for this stripped down XSD can be found at
** http://java.sun.com/xml/ns/javaee/jsp_2_1.xsd
- ** This XSD contains only the functional elements for programatic use.
+ ** This XSD contains only the functional elements for programmatic use.
-->
<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema";
diff --git a/java/javax/servlet/resources/web-jsptaglibrary_1_1.dtd
b/java/javax/servlet/resources/web-jsptaglibrary_1_1.dtd
index 47cdf06be5..acd148f360 100644
--- a/java/javax/servlet/resources/web-jsptaglibrary_1_1.dtd
+++ b/java/javax/servlet/resources/web-jsptaglibrary_1_1.dtd
@@ -39,7 +39,7 @@ shortname a simple default short name that could be used by
prefix value in taglib directives
uri a uri uniquely identifying this taglib
info a simple string describing the "use" of this taglib,
- should be user discernable
+ should be user discernible
-->
<!ELEMENT taglib (tlibversion, jspversion?, shortname, uri?, info?, tag+) >
diff --git a/java/javax/servlet/resources/web-jsptaglibrary_1_2.dtd
b/java/javax/servlet/resources/web-jsptaglibrary_1_2.dtd
index da8d1a7eaa..0f87842379 100644
--- a/java/javax/servlet/resources/web-jsptaglibrary_1_2.dtd
+++ b/java/javax/servlet/resources/web-jsptaglibrary_1_2.dtd
@@ -62,7 +62,7 @@ small-icon optional small-icon that can be used by tools
large-icon optional large-icon that can be used by tools
description a simple string describing the "use" of this taglib,
- should be user discernable
+ should be user discernible
validator optional TagLibraryValidator information
diff --git a/java/javax/servlet/resources/web-jsptaglibrary_2_0.xsd
b/java/javax/servlet/resources/web-jsptaglibrary_2_0.xsd
index 6ecd8ee890..0e2b96564a 100644
--- a/java/javax/servlet/resources/web-jsptaglibrary_2_0.xsd
+++ b/java/javax/servlet/resources/web-jsptaglibrary_2_0.xsd
@@ -669,7 +669,7 @@
The taglib tag is the document root, it defines:
description a simple string describing the "use" of this taglib,
- should be user discernable
+ should be user discernible
display-name the display-name element contains a
short name that is intended to be displayed
diff --git a/java/javax/servlet/resources/web-jsptaglibrary_2_1.xsd
b/java/javax/servlet/resources/web-jsptaglibrary_2_1.xsd
index 2714f78e78..00975cd093 100644
--- a/java/javax/servlet/resources/web-jsptaglibrary_2_1.xsd
+++ b/java/javax/servlet/resources/web-jsptaglibrary_2_1.xsd
@@ -18,7 +18,7 @@
-->
<!--
- ** This XSD contains only the programatic elements required for an
implementation.
+ ** This XSD contains only the programmatic elements required for an
implementation.
** For the XSD from Sun that includes documentation and other copyrighted
information
** please refer to
http://java.sun.com/xml/ns/javaee/web-jsptaglibrary_2_1.xsd for a fully
documented and latest
** XSD.
diff --git a/java/javax/websocket/Decoder.java
b/java/javax/websocket/Decoder.java
index 8733aa97df..52d7391353 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
+ */
void init(EndpointConfig endpointConfig);
+ /**
+ * Destroy the decoder.
+ */
void destroy();
interface Binary<T> extends Decoder {
diff --git a/java/javax/websocket/Encoder.java
b/java/javax/websocket/Encoder.java
index 5c6a211c26..22a225b628 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
+ */
void init(EndpointConfig endpointConfig);
+ /**
+ * Destroy the decoder.
+ */
void destroy();
interface Text<T> extends Encoder {
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
