This is an automated email from the ASF dual-hosted git repository. markt pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push: new f969a8f1 Fix Javadoc warnings for Servlet API when building with Java 16 f969a8f1 is described below commit f969a8f19797e41a70956a66317bdaa72a398158 Author: Mark Thomas <ma...@apache.org> AuthorDate: Thu Aug 26 11:45:09 2021 +0100 Fix Javadoc warnings for Servlet API when building with Java 16 --- java/jakarta/servlet/GenericFilter.java | 3 + java/jakarta/servlet/MultipartConfigElement.java | 50 ++++++++++++- java/jakarta/servlet/Registration.java | 11 +++ java/jakarta/servlet/ServletContext.java | 7 ++ .../servlet/ServletContextAttributeEvent.java | 7 ++ java/jakarta/servlet/ServletRegistration.java | 40 +++++++++++ .../servlet/ServletRequestAttributeEvent.java | 7 ++ java/jakarta/servlet/ServletSecurityElement.java | 16 ++++- java/jakarta/servlet/SessionCookieConfig.java | 37 +++++++++- java/jakarta/servlet/SessionTrackingMode.java | 13 ++++ java/jakarta/servlet/UnavailableException.java | 17 ++++- .../servlet/descriptor/JspConfigDescriptor.java | 21 +++++- .../descriptor/JspPropertyGroupDescriptor.java | 82 +++++++++++++++++++++- .../servlet/descriptor/TaglibDescriptor.java | 15 +++- java/jakarta/servlet/http/Cookie.java | 16 ++++- java/jakarta/servlet/http/HttpServlet.java | 5 +- java/jakarta/servlet/http/HttpServletRequest.java | 5 ++ .../servlet/http/HttpSessionBindingEvent.java | 8 ++- java/jakarta/servlet/http/MappingMatch.java | 22 ++++++ 19 files changed, 368 insertions(+), 14 deletions(-) diff --git a/java/jakarta/servlet/GenericFilter.java b/java/jakarta/servlet/GenericFilter.java index 210c225..3cdb815 100644 --- a/java/jakarta/servlet/GenericFilter.java +++ b/java/jakarta/servlet/GenericFilter.java @@ -30,6 +30,9 @@ public abstract class GenericFilter implements Filter, FilterConfig, Serializabl private static final long serialVersionUID = 1L; + /** + * The filter configuration. + */ private volatile FilterConfig filterConfig; diff --git a/java/jakarta/servlet/MultipartConfigElement.java b/java/jakarta/servlet/MultipartConfigElement.java index f30101c..dfae9d6 100644 --- a/java/jakarta/servlet/MultipartConfigElement.java +++ b/java/jakarta/servlet/MultipartConfigElement.java @@ -19,8 +19,11 @@ package jakarta.servlet; import jakarta.servlet.annotation.MultipartConfig; /** + * The programmatic equivalent of + * {@link jakarta.servlet.annotation.MultipartConfig} used to configure + * multi-part handling for a Servlet when registering a Servlet via code. + * * @since Servlet 3.0 - * TODO SERVLET3 - Add comments */ public class MultipartConfigElement { @@ -29,6 +32,12 @@ public class MultipartConfigElement { private final long maxRequestSize;// = -1; private final int fileSizeThreshold;// = 0; + /** + * Create a programmatic multi-part configuration with a specific location + * and defaults for the remaining configuration elements. + * + * @param location The temporary location to store files + */ public MultipartConfigElement(String location) { // Keep empty string default if location is null if (location != null) { @@ -41,6 +50,17 @@ public class MultipartConfigElement { this.fileSizeThreshold = 0; } + /** + * Create a programmatic multi-part configuration from the individual + * configuration elements. + * + * @param location The temporary location to store files + * @param maxFileSize The maximum permitted size for a single file + * @param maxRequestSize The maximum permitted size for a request + * @param fileSizeThreshold The size above which the file is save in the + * temporary location rather than retained in + * memory. + */ public MultipartConfigElement(String location, long maxFileSize, long maxRequestSize, int fileSizeThreshold) { // Keep empty string default if location is null @@ -60,6 +80,12 @@ public class MultipartConfigElement { } } + /** + * Create a programmatic configuration from an annotation. + * + * @param annotation The source annotation to copy to create the + * programmatic equivalent. + */ public MultipartConfigElement(MultipartConfig annotation) { location = annotation.location(); maxFileSize = annotation.maxFileSize(); @@ -67,18 +93,40 @@ public class MultipartConfigElement { fileSizeThreshold = annotation.fileSizeThreshold(); } + /** + * Obtain the location where temporary files should be stored. + * + * @return the location where temporary files should be stored. + */ public String getLocation() { return location; } + /** + * Obtain the maximum permitted size for a single file. + * + * @return the maximum permitted size for a single file. + */ public long getMaxFileSize() { return maxFileSize; } + /** + * Obtain the maximum permitted size for a single request. + * + * @return the maximum permitted size for a single request. + */ public long getMaxRequestSize() { return maxRequestSize; } + /** + * Obtain the size above which the file is save in the temporary location + * rather than retained in memory. + * + * @return the size above which the file is save in the temporary location + * rather than retained in memory. + */ public int getFileSizeThreshold() { return fileSizeThreshold; } diff --git a/java/jakarta/servlet/Registration.java b/java/jakarta/servlet/Registration.java index 45f3934..ec36532 100644 --- a/java/jakarta/servlet/Registration.java +++ b/java/jakarta/servlet/Registration.java @@ -21,12 +21,23 @@ import java.util.Set; /** * Common interface for the registration of Filters and Servlets. + * * @since Servlet 3.0 */ public interface Registration { + /** + * Obtain the name of the Servlet. + * + * @return the name of the Servlet. + */ public String getName(); + /** + * Obtain the name of the implementation class for the Servlet. + * + * @return the name of the implementation class for the Servlet. + */ public String getClassName(); /** diff --git a/java/jakarta/servlet/ServletContext.java b/java/jakarta/servlet/ServletContext.java index 3c8894c..301a3e0 100644 --- a/java/jakarta/servlet/ServletContext.java +++ b/java/jakarta/servlet/ServletContext.java @@ -51,9 +51,16 @@ import jakarta.servlet.descriptor.JspConfigDescriptor; */ public interface ServletContext { + /** + * The name of the ServletContext attribute that holds the temporary file + * location for the web application. + */ public static final String TEMPDIR = "jakarta.servlet.context.tempdir"; /** + * The name of the ServletContext attribute that holds the ordered list of + * web fragments for this web application. + * * @since Servlet 3.0 */ public static final String ORDERED_LIBS = "jakarta.servlet.context.orderedLibs"; diff --git a/java/jakarta/servlet/ServletContextAttributeEvent.java b/java/jakarta/servlet/ServletContextAttributeEvent.java index edbb266..5141352 100644 --- a/java/jakarta/servlet/ServletContextAttributeEvent.java +++ b/java/jakarta/servlet/ServletContextAttributeEvent.java @@ -26,7 +26,14 @@ package jakarta.servlet; public class ServletContextAttributeEvent extends ServletContextEvent { private static final long serialVersionUID = 1L; + /** + * Attribute name. + */ private final String name; + + /** + * Attribute value. + */ private final Object value; /** diff --git a/java/jakarta/servlet/ServletRegistration.java b/java/jakarta/servlet/ServletRegistration.java index f78bde0..c1737de 100644 --- a/java/jakarta/servlet/ServletRegistration.java +++ b/java/jakarta/servlet/ServletRegistration.java @@ -58,6 +58,13 @@ public interface ServletRegistration extends Registration { */ public Collection<String> getMappings(); + /** + * Obtain the name of the user / group under which the Servlet has been + * configured to run. + * + * @return the name of the user / group or {@code null} if none has been + * specified + */ public String getRunAsRole(); /** @@ -65,9 +72,42 @@ public interface ServletRegistration extends Registration { * methods on ServletContext may be further configured. */ public static interface Dynamic extends ServletRegistration, Registration.Dynamic { + + /** + * Set the loadOnStartup order for the Servlet + * + * @param loadOnStartup The position in the order the Servlet should be + * started (higher numbers are started after lower + * numbers) + */ public void setLoadOnStartup(int loadOnStartup); + + /** + * Add security constraints to this Servlet. + * + * @param constraint new security constraints for this Servlet + * + * @return urls currently mapped to this registration that are already + * present in web.xml + */ public Set<String> setServletSecurity(ServletSecurityElement constraint); + + /** + * Set the multi-part configuration for the associated Servlet. To clear + * the multi-part configuration specify <code>null</code> as the new + * value. + * + * @param multipartConfig The configuration to associate with the + * Servlet + */ public void setMultipartConfig(MultipartConfigElement multipartConfig); + + /** + * Set the name of the user / group under which the Servlet should be + * configured to run. + * + * @param roleName name of the user / group or {@code null} if none + */ public void setRunAsRole(String roleName); } } diff --git a/java/jakarta/servlet/ServletRequestAttributeEvent.java b/java/jakarta/servlet/ServletRequestAttributeEvent.java index abbdc31..310c02f 100644 --- a/java/jakarta/servlet/ServletRequestAttributeEvent.java +++ b/java/jakarta/servlet/ServletRequestAttributeEvent.java @@ -26,7 +26,14 @@ package jakarta.servlet; public class ServletRequestAttributeEvent extends ServletRequestEvent { private static final long serialVersionUID = 1L; + /** + * Attribute name. + */ private final String name; + + /** + * Attribute value. + */ private final Object value; /** diff --git a/java/jakarta/servlet/ServletSecurityElement.java b/java/jakarta/servlet/ServletSecurityElement.java index 25a98d0c..6349406 100644 --- a/java/jakarta/servlet/ServletSecurityElement.java +++ b/java/jakarta/servlet/ServletSecurityElement.java @@ -27,9 +27,11 @@ import jakarta.servlet.annotation.HttpMethodConstraint; import jakarta.servlet.annotation.ServletSecurity; /** + * The programmatic equivalent of + * {@link jakarta.servlet.annotation.ServletSecurity} used to configre + * security constraints for a Servlet. * * @since Servlet 3.0 - * TODO SERVLET3 - Add comments */ public class ServletSecurityElement extends HttpConstraintElement { @@ -108,11 +110,23 @@ public class ServletSecurityElement extends HttpConstraintElement { addHttpMethodConstraints(l); } + /** + * Obtain the collection of security constraints configured for specific + * methods. + * + * @return The security constraints for specific methods + */ public Collection<HttpMethodConstraintElement> getHttpMethodConstraints() { Collection<HttpMethodConstraintElement> result = new HashSet<>(methodConstraints.values()); return result; } + /** + * Obtain the collection HTTP methods for which security constraints have + * been defined. + * + * @return The names of the HTTP methods + */ public Collection<String> getMethodNames() { Collection<String> result = new HashSet<>(methodConstraints.keySet()); return result; diff --git a/java/jakarta/servlet/SessionCookieConfig.java b/java/jakarta/servlet/SessionCookieConfig.java index 6c683a7..936e49d 100644 --- a/java/jakarta/servlet/SessionCookieConfig.java +++ b/java/jakarta/servlet/SessionCookieConfig.java @@ -34,6 +34,11 @@ public interface SessionCookieConfig { */ public void setName(String name); + /** + * Obtain the name to use for the session cookies. + * + * @return the name to use for session cookies. + */ public String getName(); /** @@ -46,6 +51,11 @@ public interface SessionCookieConfig { */ public void setDomain(String domain); + /** + * Obtain the domain to use for session cookies. + * + * @return the domain to use for session cookies. + */ public String getDomain(); /** @@ -58,6 +68,12 @@ public interface SessionCookieConfig { */ public void setPath(String path); + /** + * Obtain the path to use for session cookies. This is normally the context + * path. + * + * @return The path to use for session cookies. + */ public String getPath(); /** @@ -70,6 +86,11 @@ public interface SessionCookieConfig { */ public void setComment(String comment); + /** + * Obtain the comment to use for session cookies. + * + * @return the comment to use for session cookies. + */ public String getComment(); /** @@ -82,6 +103,11 @@ public interface SessionCookieConfig { */ public void setHttpOnly(boolean httpOnly); + /** + * Will session cookies be created with the httpOnly flag set? + * + * @return {@code true} if the flag should be set, otherwise {@code false} + */ public boolean isHttpOnly(); /** @@ -94,6 +120,11 @@ public interface SessionCookieConfig { */ public void setSecure(boolean secure); + /** + * Will session cookies be created with the secure flag set? + * + * @return {@code true} if the flag should be set, otherwise {@code false} + */ public boolean isSecure(); /** @@ -105,6 +136,10 @@ public interface SessionCookieConfig { */ public void setMaxAge(int MaxAge); + /** + * Obtain the maximum age to set for a session cookie. + * + * @return the maximum age in seconds + */ public int getMaxAge(); - } diff --git a/java/jakarta/servlet/SessionTrackingMode.java b/java/jakarta/servlet/SessionTrackingMode.java index 0ca8684..8244fdf 100644 --- a/java/jakarta/servlet/SessionTrackingMode.java +++ b/java/jakarta/servlet/SessionTrackingMode.java @@ -17,10 +17,23 @@ package jakarta.servlet; /** + * Defines the permitted options for configuring the session tracking mode. + * * @since Servlet 3.0 */ public enum SessionTrackingMode { + /** + * Use HTTP cookies. + */ COOKIE, + + /** + * Use url rewriting (also known as path parameter) + */ URL, + + /** + * Use SSL session. + */ SSL } diff --git a/java/jakarta/servlet/UnavailableException.java b/java/jakarta/servlet/UnavailableException.java index e45ec64..73132ee 100644 --- a/java/jakarta/servlet/UnavailableException.java +++ b/java/jakarta/servlet/UnavailableException.java @@ -42,9 +42,20 @@ public class UnavailableException extends ServletException { private static final long serialVersionUID = 1L; - private final Servlet servlet; // what's unavailable - private final boolean permanent; // needs admin action? - private final int seconds; // unavailability estimate + /** + * The Servlet that is unavailable. + */ + private final Servlet servlet; + + /** + * Is the issue permanent - i.e. is administrator action required? + */ + private final boolean permanent; + + /** + * The estimate of how long the Servlet will be unavailable. + */ + private final int seconds; /** * @param servlet diff --git a/java/jakarta/servlet/descriptor/JspConfigDescriptor.java b/java/jakarta/servlet/descriptor/JspConfigDescriptor.java index 12d0c01..78b78de 100644 --- a/java/jakarta/servlet/descriptor/JspConfigDescriptor.java +++ b/java/jakarta/servlet/descriptor/JspConfigDescriptor.java @@ -19,10 +19,29 @@ package jakarta.servlet.descriptor; import java.util.Collection; /** + * This interface exposes the JSP specific configuration information obtain ed + * from the deployment descriptors. It is primarily provided so that JSP + * implementations do not have to parse deployment descriptors. + * * @since Servlet 3.0 - * TODO SERVLET3 - Add comments */ public interface JspConfigDescriptor { + + /** + * Provide the set of tag library descriptors obtained from the + * <jsp-config> elements in the web application's deployment + * descriptors. + * + * @return the tag library descriptors + */ public Collection<TaglibDescriptor> getTaglibs(); + + /** + * Provide the set of JSP property groups obtained from the + * <jsp-config> elements in the web application's deployment + * descriptors. + * + * @return the JSP property groups + */ public Collection<JspPropertyGroupDescriptor> getJspPropertyGroups(); } diff --git a/java/jakarta/servlet/descriptor/JspPropertyGroupDescriptor.java b/java/jakarta/servlet/descriptor/JspPropertyGroupDescriptor.java index 94d974d..a1c5356 100644 --- a/java/jakarta/servlet/descriptor/JspPropertyGroupDescriptor.java +++ b/java/jakarta/servlet/descriptor/JspPropertyGroupDescriptor.java @@ -19,20 +19,100 @@ package jakarta.servlet.descriptor; import java.util.Collection; /** + * Represents the JSP property groups in the deployment descriptors. + * * @since Servlet 3.0 - * TODO SERVLET3 - Add comments */ public interface JspPropertyGroupDescriptor { + + /** + * Obtain the patterns to which this group applies. + * + * @return the patterns to which this group applies + */ public Collection<String> getUrlPatterns(); + + /** + * Is Expression Language ignored for this group? + * + * @return {@code true} if EL is ignored, otherwise {@code false} + */ public String getElIgnored(); + + /** + * Obtain the page encoding for this group. + * + * @return the page encoding for this group + */ public String getPageEncoding(); + + /** + * Is scripting disabled for this group? + * + * @return {@code true} if scripting is disabled, otherwise {@code false} + */ public String getScriptingInvalid(); + + /** + * Should the JSPs in this group be treated as JSP documents? + * + * @return {@code true} if the JSPs should be treated as JSP documents, + * otherwise {@code false} + */ public String getIsXml(); + + /** + * Obtain the preludes to include for this group. + * + * @return the preludes to include for this group + */ public Collection<String> getIncludePreludes(); + + /** + * Obtain the codas to include for this group. + * + * @return the codas to include for this group. + */ public Collection<String> getIncludeCodas(); + + /** + * Is the deferred El syntax <code>#{...}</code> allowed to be used as a + * literal in this group? + * + * @return {@code true} if the deferred EL syntax is allowed to be used as + * a literal, otherwise {@code false} + */ public String getDeferredSyntaxAllowedAsLiteral(); + + /** + * Should the JSPs in this group have template text that onyl contains + * whitespace removed? + * + * @return {@code true} if the whitespace be removed, otherwise + * {@code false} + */ public String getTrimDirectiveWhitespaces(); + + /** + * Obtain the default content type this group of JSP pages.# + * + * @return the default content type this group of JSP pages + */ public String getDefaultContentType(); + + /** + * Obtain the per-page buffer configuration for this group of JSP pages. + * + * @return the per-page buffer configuration for this group of JSP pages + */ public String getBuffer(); + + /** + * Should an error be raised at translation time for a page in this group if + * the page contains a reference (e.g. a tag) to a undeclared namespace. + * + * @return {@code true} if an error should be raised, otherwise + * {@code false} + */ public String getErrorOnUndeclaredNamespace(); } diff --git a/java/jakarta/servlet/descriptor/TaglibDescriptor.java b/java/jakarta/servlet/descriptor/TaglibDescriptor.java index e4e82a4..4971093 100644 --- a/java/jakarta/servlet/descriptor/TaglibDescriptor.java +++ b/java/jakarta/servlet/descriptor/TaglibDescriptor.java @@ -17,10 +17,23 @@ package jakarta.servlet.descriptor; /** + * Represents a taglib descriptor definitions in the deployment descriptor. + * * @since Servlet 3.0 - * TODO SERVLET3 - Add comments */ public interface TaglibDescriptor { + + /** + * Obtain the URI for the tag library. + * + * @return the URI for the tag library + */ public String getTaglibURI(); + + /** + * Obtain the location of the tag library. + * + * @return the location of the tag library + */ public String getTaglibLocation(); } diff --git a/java/jakarta/servlet/http/Cookie.java b/java/jakarta/servlet/http/Cookie.java index 62921f3..85d67b7 100644 --- a/java/jakarta/servlet/http/Cookie.java +++ b/java/jakarta/servlet/http/Cookie.java @@ -110,12 +110,24 @@ public class Cookie implements Cloneable, Serializable { private static final long serialVersionUID = 2L; + /** + * Cookie name. + */ private final String name; + + /** + * Cookie value. + */ private String value; - private int version = 0; // ;Version=1 ... means RFC 2109 style + /** + * Cookie version value. {@code ;Version=1 ...} means RFC 2109 style. + */ + private int version = 0; - // Attributes encoded in the header's cookie fields. + /** + * Attributes encoded in the header's cookie fields. + */ private volatile Map<String,String> attributes; private static final String COMMENT = "Comment"; diff --git a/java/jakarta/servlet/http/HttpServlet.java b/java/jakarta/servlet/http/HttpServlet.java index e94c473..ea9976c 100644 --- a/java/jakarta/servlet/http/HttpServlet.java +++ b/java/jakarta/servlet/http/HttpServlet.java @@ -94,7 +94,10 @@ public abstract class HttpServlet extends GenericServlet { private static final String LSTRING_FILE = "jakarta.servlet.http.LocalStrings"; private static final ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE); - private final Object cachedAllowHeaderValueLock = new Object(); + private final transient Object cachedAllowHeaderValueLock = new Object(); + /** + * Cached value of the HTTP {@code Allow} header for this servlet. + */ private volatile String cachedAllowHeaderValue = null; diff --git a/java/jakarta/servlet/http/HttpServletRequest.java b/java/jakarta/servlet/http/HttpServletRequest.java index 076fa33..1984299 100644 --- a/java/jakarta/servlet/http/HttpServletRequest.java +++ b/java/jakarta/servlet/http/HttpServletRequest.java @@ -171,6 +171,11 @@ public interface HttpServletRequest extends ServletRequest { */ public int getIntHeader(String name); + /** + * Obtain the mapping information for this request. + * + * @return the mapping information for this request + */ public default HttpServletMapping getHttpServletMapping() { return new HttpServletMapping() { diff --git a/java/jakarta/servlet/http/HttpSessionBindingEvent.java b/java/jakarta/servlet/http/HttpSessionBindingEvent.java index d79796f..ed70b05 100644 --- a/java/jakarta/servlet/http/HttpSessionBindingEvent.java +++ b/java/jakarta/servlet/http/HttpSessionBindingEvent.java @@ -35,10 +35,14 @@ public class HttpSessionBindingEvent extends HttpSessionEvent { private static final long serialVersionUID = 1L; - /* The name to which the object is being bound or unbound */ + /** + * The name to which the object is being bound or unbound. + */ private final String name; - /* The object is being bound or unbound */ + /** + * The object is being bound or unbound. + */ private final Object value; /** diff --git a/java/jakarta/servlet/http/MappingMatch.java b/java/jakarta/servlet/http/MappingMatch.java index 1bf4992..4a7fc77 100644 --- a/java/jakarta/servlet/http/MappingMatch.java +++ b/java/jakarta/servlet/http/MappingMatch.java @@ -23,9 +23,31 @@ package jakarta.servlet.http; */ public enum MappingMatch { + /** + * The request was mapped to the servlet via the context root URL pattern of + * {@code ""}. + */ CONTEXT_ROOT, + + /** + * The request was mapped to the servlet via the default servlet URL pattern + * of {@code "/"} . + */ DEFAULT, + + /** + * The request was mapped to the servlet using an exact URL pattern match. + */ EXACT, + + /** + * The request was mapped to the servlet using an extension URL pattern + * match. + */ EXTENSION, + + /** + * The request was mapped to the servlet using a path URL pattern. + */ PATH } --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org