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
commit 0218af763b6990bab49d6d0132326bf5b4d75914
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Fri Apr 14 13:02:13 2023 +0100
Align with 10.1.x
Javadoc improvements
---
java/javax/security/auth/message/ClientAuth.java | 32 +++++++++++++++++++++
java/javax/security/auth/message/ServerAuth.java | 33 +++++++++++++++++++++-
java/javax/servlet/Servlet.java | 2 +-
java/javax/servlet/ServletRequest.java | 7 +++--
java/javax/servlet/http/Cookie.java | 17 +++++++++++
java/javax/servlet/http/HttpServlet.java | 13 +++++----
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 +--
11 files changed, 127 insertions(+), 29 deletions(-)
diff --git a/java/javax/security/auth/message/ClientAuth.java
b/java/javax/security/auth/message/ClientAuth.java
index a8f9a77ae7..5fc5fe6733 100644
--- a/java/javax/security/auth/message/ClientAuth.java
+++ b/java/javax/security/auth/message/ClientAuth.java
@@ -20,11 +20,43 @@ import javax.security.auth.Subject;
public interface ClientAuth {
+ /**
+ * Secure (authenticate) the request.
+ *
+ * @param messageInfo The associated request and response
+ * @param clientSubject The subject that represents the source of the
request
+ *
+ * @return An AuthStatus instance that represents the result of the
authentication
+ *
+ * @throws AuthException If the a failure occurred in a manner that
prevented the failure from being communicated
+ * via messageInfo
+ */
AuthStatus secureRequest(MessageInfo messageInfo, Subject clientSubject)
throws AuthException;
+ /**
+ * Validate a response.
+ *
+ * @param messageInfo The associated request and response
+ * @param clientSubject The subject that represents the recipient of the
response
+ * @param serviceSubject The subject that represents the source of the
response
+ *
+ * @return An AuthStatus instance that represents the result of the
validation
+ *
+ * @throws AuthException If the a failure occurred in a manner that
prevented the failure from being communicated
+ * via messageInfo
+ */
AuthStatus validateResponse(MessageInfo messageInfo, Subject
clientSubject, Subject serviceSubject)
throws AuthException;
+ /**
+ * Remove principals and/or credentials from the subject that were
previously added by this authentication
+ * mechanism.
+ *
+ * @param messageInfo The associated request and response
+ * @param subject The subject to clean
+ *
+ * @throws AuthException If the a failure occurred
+ */
void cleanSubject(MessageInfo messageInfo, Subject subject) throws
AuthException;
}
diff --git a/java/javax/security/auth/message/ServerAuth.java
b/java/javax/security/auth/message/ServerAuth.java
index 23f5c66ecb..392bc5094b 100644
--- a/java/javax/security/auth/message/ServerAuth.java
+++ b/java/javax/security/auth/message/ServerAuth.java
@@ -20,10 +20,41 @@ import javax.security.auth.Subject;
public interface ServerAuth {
- AuthStatus validateRequest(MessageInfo messageInfo, Subject clientSubject,
Subject serviceSubject)
+ /**
+ * Validate the request.
+ *
+ * @param messageInfo The associated request and response
+ * @param clientSubject The subject that represents the source of the
request
+ * @param serviceSubject The subject that represents the recipient of the
request
+ *
+ * @return An AuthStatus instance that represents the result of the
validation
+ *
+ * @throws AuthException If the a failure occurred in a manner that
prevented the failure from being communicated
+ * via messageInfo
+ */ AuthStatus validateRequest(MessageInfo messageInfo, Subject
clientSubject, Subject serviceSubject)
throws AuthException;
+ /**
+ * Secure (authenticate) the response.
+ *
+ * @param messageInfo The associated request and response
+ * @param serviceSubject The subject that represents the source of the
response
+ *
+ * @return An AuthStatus instance that represents the result of the
authentication
+ *
+ * @throws AuthException If the a failure occurred in a manner that
prevented the failure from being communicated
+ * via messageInfo
+ */
AuthStatus secureResponse(MessageInfo messageInfo, Subject serviceSubject)
throws AuthException;
+ /**
+ * Remove principals and/or credentials from the subject that were
previously added by this authentication
+ * mechanism.
+ *
+ * @param messageInfo The associated request and response
+ * @param subject The subject to clean
+ *
+ * @throws AuthException If the a failure occurred
+ */
void cleanSubject(MessageInfo messageInfo, Subject subject) throws
AuthException;
}
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 1d1ee6fd94..bda89e30bf 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;
@@ -84,11 +85,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/Cookie.java
b/java/javax/servlet/http/Cookie.java
index 99137476d5..0415a1b618 100644
--- a/java/javax/servlet/http/Cookie.java
+++ b/java/javax/servlet/http/Cookie.java
@@ -179,6 +179,7 @@ public class Cookie implements Cloneable, Serializable {
comment = purpose;
}
+
/**
* Returns the comment describing the purpose of this cookie, or
<code>null</code> if the cookie has no comment.
*
@@ -190,6 +191,7 @@ public class Cookie implements Cloneable, Serializable {
return comment;
}
+
/**
* Specifies the domain within which this cookie should be presented.
* <p>
@@ -207,6 +209,7 @@ public class Cookie implements Cloneable, Serializable {
domain = pattern.toLowerCase(Locale.ENGLISH); // IE allegedly needs
this
}
+
/**
* Returns the domain name set for this cookie. The form of the domain
name is set by RFC 2109.
*
@@ -218,6 +221,7 @@ public class Cookie implements Cloneable, Serializable {
return domain;
}
+
/**
* Sets the maximum age of the cookie in seconds.
* <p>
@@ -236,6 +240,7 @@ public class Cookie implements Cloneable, Serializable {
maxAge = expiry;
}
+
/**
* Returns the maximum age of the cookie, specified in seconds, By
default, <code>-1</code> indicating the cookie
* will persist until browser shutdown.
@@ -249,6 +254,7 @@ public class Cookie implements Cloneable, Serializable {
return maxAge;
}
+
/**
* Specifies a path for the cookie to which the client should return the
cookie.
* <p>
@@ -266,6 +272,7 @@ public class Cookie implements Cloneable, Serializable {
path = uri;
}
+
/**
* Returns the path on the server to which the browser returns this
cookie. The cookie is visible to all subpaths on
* the server.
@@ -278,6 +285,7 @@ public class Cookie implements Cloneable, Serializable {
return path;
}
+
/**
* Indicates to the browser whether the cookie should only be sent using a
secure protocol, such as HTTPS or SSL.
* <p>
@@ -292,6 +300,7 @@ public class Cookie implements Cloneable, Serializable {
secure = flag;
}
+
/**
* Returns <code>true</code> if the browser is sending cookies only over a
secure protocol, or <code>false</code> if
* the browser can send cookies using any protocol.
@@ -304,6 +313,7 @@ public class Cookie implements Cloneable, Serializable {
return secure;
}
+
/**
* Returns the name of the cookie. The name cannot be changed after
creation.
*
@@ -313,6 +323,7 @@ public class Cookie implements Cloneable, Serializable {
return name;
}
+
/**
* Assigns a new value to a cookie after the cookie is created. If you use
a binary value, you may want to use
* BASE64 encoding.
@@ -330,6 +341,7 @@ public class Cookie implements Cloneable, Serializable {
value = newValue;
}
+
/**
* Returns the value of the cookie.
*
@@ -342,6 +354,7 @@ public class Cookie implements Cloneable, Serializable {
return value;
}
+
/**
* Returns the version of the protocol this cookie complies with. Version
1 complies with RFC 2109, and version 0
* complies with the original cookie specification drafted by Netscape.
Cookies provided by a browser use and
@@ -355,6 +368,7 @@ public class Cookie implements Cloneable, Serializable {
return version;
}
+
/**
* Sets the version of the cookie protocol this cookie complies with.
Version 0 complies with the original Netscape
* cookie specification. Version 1 complies with RFC 2109.
@@ -370,6 +384,7 @@ public class Cookie implements Cloneable, Serializable {
version = v;
}
+
/**
* Overrides the standard <code>java.lang.Object.clone</code> method to
return a copy of this cookie.
*/
@@ -382,6 +397,7 @@ public class Cookie implements Cloneable, Serializable {
}
}
+
/**
* Sets the flag that controls if this cookie will be hidden from scripts
on the client side.
*
@@ -393,6 +409,7 @@ public class Cookie implements Cloneable, Serializable {
this.httpOnly = httpOnly;
}
+
/**
* Gets the flag that controls if this cookie will be hidden from scripts
on the client side.
*
diff --git a/java/javax/servlet/http/HttpServlet.java
b/java/javax/servlet/http/HttpServlet.java
index 7cdc694e01..2895720127 100644
--- a/java/javax/servlet/http/HttpServlet.java
+++ b/java/javax/servlet/http/HttpServlet.java
@@ -40,6 +40,7 @@ import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.WriteListener;
+
/**
* Provides an abstract class to be subclassed to create an HTTP servlet
suitable for a Web site. A subclass of
* <code>HttpServlet</code> must override at least one method, usually one of
these:
@@ -100,9 +101,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
@@ -197,9 +198,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/javax/servlet/http/HttpServletResponse.java
b/java/javax/servlet/http/HttpServletResponse.java
index f779b4fc53..dfba4b682e 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 4999e12f9c..174e9479be 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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
