This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 10.1.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit c2dc6683fd1b04af52b57a933756e79d64f15de6
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Fri Apr 14 12:01:25 2023 +0100
Align with 11.0.x
Improve Javadoc wording
Fix/improve formatting
---
java/jakarta/servlet/Servlet.java | 2 +-
java/jakarta/servlet/ServletContext.java | 7 +++--
java/jakarta/servlet/ServletRequest.java | 26 ++++++++-----------
java/jakarta/servlet/http/HttpServlet.java | 12 ++++-----
java/jakarta/servlet/http/HttpServletResponse.java | 30 +++++++++++++++-------
.../servlet/http/HttpServletResponseWrapper.java | 2 +-
java/jakarta/servlet/jsp/JspPage.java | 15 +++++++----
java/jakarta/servlet/jsp/tagext/IterationTag.java | 1 -
8 files changed, 53 insertions(+), 42 deletions(-)
diff --git a/java/jakarta/servlet/Servlet.java
b/java/jakarta/servlet/Servlet.java
index c234a1f4df..838b4f0d25 100644
--- a/java/jakarta/servlet/Servlet.java
+++ b/java/jakarta/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/jakarta/servlet/ServletContext.java
b/java/jakarta/servlet/ServletContext.java
index 99e731df80..fe7945c741 100644
--- a/java/jakarta/servlet/ServletContext.java
+++ b/java/jakarta/servlet/ServletContext.java
@@ -355,8 +355,7 @@ public interface ServletContext {
* supported attributes can be retrieved using
<code>getAttributeNames</code>.
* <p>
* The attribute is returned as a <code>java.lang.Object</code> or some
subclass. Attribute names should follow the
- * same convention as package names. The Java Servlet API specification
reserves names matching <code>java.*</code>,
- * <code>javax.*</code>, and <code>sun.*</code>.
+ * same convention as package names. The Jakarta EE platform reserves
names matching <code>jakarta.*</code>.
*
* @param name a <code>String</code> specifying the name of the attribute
*
@@ -387,8 +386,8 @@ public interface ServletContext {
* <p>
* If a null value is passed, the effect is the same as calling
<code>removeAttribute()</code>.
* <p>
- * Attribute names should follow the same convention as package names. The
Java Servlet API specification reserves
- * names matching <code>java.*</code>, <code>javax.*</code>, and
<code>sun.*</code>.
+ * Attribute names should follow the same convention as package names. The
Jakarta EE platform reserves names
+ * matching <code>jakarta.*</code>.
*
* @param name a <code>String</code> specifying the name of the attribute
* @param object an <code>Object</code> representing the attribute to be
bound
diff --git a/java/jakarta/servlet/ServletRequest.java
b/java/jakarta/servlet/ServletRequest.java
index b0865c21d3..7d12677ef0 100644
--- a/java/jakarta/servlet/ServletRequest.java
+++ b/java/jakarta/servlet/ServletRequest.java
@@ -18,6 +18,7 @@ package jakarta.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;
@@ -44,10 +45,8 @@ public interface ServletRequest {
* the client. Attributes can also be set programmatically using {@link
ServletRequest#setAttribute}. This allows
* information to be embedded into a request before a {@link
RequestDispatcher} call.
* <p>
- * Attribute names should follow the same conventions as package names.
Names beginning with <code>java.*</code> and
- * <code>javax.*</code> are reserved for use by the Servlet specification.
Names beginning with <code>sun.*</code>,
- * <code>com.sun.*</code>, <code>oracle.*</code> and
<code>com.oracle.*</code>) are reserved for use by Oracle
- * Corporation.
+ * Attribute names should follow the same conventions as package names.
Names beginning with <code>jakarta.*</code>
+ * are reserved for use by the Jakarta EE platform.
*
* @param name a <code>String</code> specifying the name of the attribute
*
@@ -84,11 +83,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
@@ -255,10 +254,9 @@ public interface ServletRequest {
* Stores an attribute in this request. Attributes are reset between
requests. This method is most often used in
* conjunction with {@link RequestDispatcher}.
* <p>
- * Attribute names should follow the same conventions as package names.
Names beginning with <code>java.*</code> and
- * <code>javax.*</code> are reserved for use by the Servlet specification.
Names beginning with <code>sun.*</code>,
- * <code>com.sun.*</code>, <code>oracle.*</code> and
<code>com.oracle.*</code>) are reserved for use by Oracle
- * Corporation. <br>
+ * Attribute names should follow the same conventions as package names.
Names beginning with <code>jakarta.*</code>
+ * are reserved for use by the Jakarta EE platform.
+ * <p>
* If the object passed in is null, the effect is the same as calling
{@link #removeAttribute}. <br>
* It is warned that when the request is dispatched from the servlet
resides in a different web application by
* <code>RequestDispatcher</code>, the object set by this method may not
be correctly retrieved in the caller
@@ -273,10 +271,8 @@ public interface ServletRequest {
* Removes an attribute from this request. This method is not generally
needed as attributes only persist as long as
* the request is being handled.
* <p>
- * Attribute names should follow the same conventions as package names.
Names beginning with <code>java.*</code> and
- * <code>javax.*</code> are reserved for use by the Servlet specification.
Names beginning with <code>sun.*</code>,
- * <code>com.sun.*</code>, <code>oracle.*</code> and
<code>com.oracle.*</code>) are reserved for use by Oracle
- * Corporation.
+ * Attribute names should follow the same conventions as package names.
Names beginning with <code>jakarta.*</code>
+ * are reserved for use by the Jakarta EE platform.
*
* @param name a <code>String</code> specifying the name of the attribute
to remove
*/
diff --git a/java/jakarta/servlet/http/HttpServlet.java
b/java/jakarta/servlet/http/HttpServlet.java
index a49eb1467a..7eff796db3 100644
--- a/java/jakarta/servlet/http/HttpServlet.java
+++ b/java/jakarta/servlet/http/HttpServlet.java
@@ -129,9 +129,9 @@ public abstract class HttpServlet extends GenericServlet {
* Overriding this method to support a GET request also automatically
supports an HTTP HEAD request. A HEAD request
* is a GET request that returns no body in the response, only the request
header fields.
* <p>
- * When overriding this method, read the request data, write the response
headers, get the response's noBodyWriter
- * or output stream object, and finally, write the response data. It's
best to include content type and encoding.
- * When using a <code>PrintWriter</code> object to return the response,
set the content type before accessing the
+ * When overriding this method, read the request data, write the response
headers, get the response's Writer or
+ * output stream object, and finally, write the response data. It's best
to include content type and encoding. When
+ * using a <code>PrintWriter</code> object to return the response, set the
content type before accessing the
* <code>PrintWriter</code> object.
* <p>
* The servlet container must write the headers before committing the
response, because in HTTP the headers must be
@@ -226,9 +226,9 @@ public abstract class HttpServlet extends GenericServlet {
* POST method allows the client to send data of unlimited length to the
Web server a single time and is useful when
* posting information such as credit card numbers.
* <p>
- * When overriding this method, read the request data, write the response
headers, get the response's noBodyWriter
- * or output stream object, and finally, write the response data. It's
best to include content type and encoding.
- * When using a <code>PrintWriter</code> object to return the response,
set the content type before accessing the
+ * When overriding this method, read the request data, write the response
headers, get the response's Writer or
+ * output stream object, and finally, write the response data. It's best
to include content type and encoding. When
+ * using a <code>PrintWriter</code> object to return the response, set the
content type before accessing the
* <code>PrintWriter</code> object.
* <p>
* The servlet container must write the headers before committing the
response, because in HTTP the headers must be
diff --git a/java/jakarta/servlet/http/HttpServletResponse.java
b/java/jakarta/servlet/http/HttpServletResponse.java
index f50dffaae3..26405e08b5 100644
--- a/java/jakarta/servlet/http/HttpServletResponse.java
+++ b/java/jakarta/servlet/http/HttpServletResponse.java
@@ -112,20 +112,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/jakarta/servlet/http/HttpServletResponseWrapper.java
b/java/jakarta/servlet/http/HttpServletResponseWrapper.java
index 5f74ad5ba7..1f474373ae 100644
--- a/java/jakarta/servlet/http/HttpServletResponseWrapper.java
+++ b/java/jakarta/servlet/http/HttpServletResponseWrapper.java
@@ -98,7 +98,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/jakarta/servlet/jsp/JspPage.java
b/java/jakarta/servlet/jsp/JspPage.java
index c9bc850af4..bb9222cf07 100644
--- a/java/jakarta/servlet/jsp/JspPage.java
+++ b/java/jakarta/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/jakarta/servlet/jsp/tagext/IterationTag.java
b/java/jakarta/servlet/jsp/tagext/IterationTag.java
index f207015f36..3fa65d162e 100644
--- a/java/jakarta/servlet/jsp/tagext/IterationTag.java
+++ b/java/jakarta/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;
/**
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
