You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2019/07/30 14:26:34 UTC
[tomcat] 01/04: Align with 8.5.x. Javadoc
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit 86ee8fc7325c4d45deed688ff47f87111d33c34d
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Tue Jul 30 15:02:54 2019 +0100
Align with 8.5.x. Javadoc
---
.../org/apache/catalina/filters/ExpiresFilter.java | 67 ++++++++++++++--------
1 file changed, 44 insertions(+), 23 deletions(-)
diff --git a/java/org/apache/catalina/filters/ExpiresFilter.java b/java/org/apache/catalina/filters/ExpiresFilter.java
index dc2c39b..983fabb 100644
--- a/java/org/apache/catalina/filters/ExpiresFilter.java
+++ b/java/org/apache/catalina/filters/ExpiresFilter.java
@@ -217,27 +217,28 @@ import org.apache.juli.logging.LogFactory;
* {@code
* <init-param>
* <param-name>ExpiresDefault</param-name>
- * <param-value><base> [plus] {<num> <type>}*</param-value>
+ * <param-value><base> [plus] (<num> <type>)*</param-value>
* </init-param>
*
* <init-param>
* <param-name>ExpiresByType type/encoding</param-name>
- * <param-value><base> [plus] {<num> <type>}*</param-value>
+ * <param-value><base> [plus] (<num> <type>)*</param-value>
* </init-param>
* }
* </pre>
* <p>
* where {@code <base>} is one of:
+ * </p>
* <ul>
* <li>{@code access}</li>
* <li>{@code now} (equivalent to '{@code access}')</li>
* <li>{@code modification}</li>
* </ul>
- * </p>
* <p>
* The {@code plus} keyword is optional. {@code <num>} should be an
* integer value (acceptable to {@code Integer.parseInt()}), and
* {@code <type>} is one of:
+ * </p>
* <ul>
* <li>{@code years}</li>
* <li>{@code months}</li>
@@ -247,6 +248,7 @@ import org.apache.juli.logging.LogFactory;
* <li>{@code minutes}</li>
* <li>{@code seconds}</li>
* </ul>
+ * <p>
* For example, any of the following directives can be used to make documents
* expire 1 month after being accessed, by default:
* </p>
@@ -296,6 +298,7 @@ import org.apache.juli.logging.LogFactory;
* <h1>Expiration headers generation eligibility</h1>
* <p>
* A response is eligible to be enriched by {@code ExpiresFilter} if :
+ * </p>
* <ol>
* <li>no expiration header is defined ({@code Expires} header or the
* {@code max-age} directive of the {@code Cache-Control} header),</li>
@@ -305,18 +308,18 @@ import org.apache.juli.logging.LogFactory;
* defined the in {@code ExpiresByType} directives or the
* {@code ExpiresDefault} directive is defined.</li>
* </ol>
- * </p>
* <p>
* Note :
+ * </p>
* <ul>
* <li>If {@code Cache-Control} header contains other directives than
* {@code max-age}, they are concatenated with the {@code max-age} directive
* that is added by the {@code ExpiresFilter}.</li>
* </ul>
- * </p>
* <h1>Expiration configuration selection</h1>
* <p>
* The expiration configuration if elected according to the following algorithm:
+ * </p>
* <ol>
* <li>{@code ExpiresByType} matching the exact content-type returned by
* {@code HttpServletResponse.getContentType()} possibly including the charset
@@ -330,7 +333,6 @@ import org.apache.juli.logging.LogFactory;
* '),</li>
* <li>{@code ExpiresDefault}</li>
* </ol>
- * </p>
* <h1>Implementation Details</h1><h2>When to write the expiration headers ?</h2>
* <p>
* The {@code ExpiresFilter} traps the 'on before write response
@@ -370,6 +372,7 @@ import org.apache.juli.logging.LogFactory;
* </p>
* <p>
* Key methods to override for extension are :
+ * </p>
* <ul>
* <li>
* {@link #isEligibleToExpirationHeaderGeneration(HttpServletRequest, XHttpServletResponse)}
@@ -377,7 +380,6 @@ import org.apache.juli.logging.LogFactory;
* <li>
* {@link #getExpirationDate(XHttpServletResponse)}</li>
* </ul>
- * </p>
* <h1>Troubleshooting</h1>
* <p>
* To troubleshoot, enable logging on the
@@ -387,14 +389,14 @@ import org.apache.juli.logging.LogFactory;
* Extract of logging.properties
* </p>
*
- * <code><pre>
+ * <code>
* org.apache.catalina.filters.ExpiresFilter.level = FINE
- * </pre></code>
+ * </code>
* <p>
* Sample of initialization log message :
* </p>
*
- * <code><pre>
+ * <code>
* Mar 26, 2010 2:01:41 PM org.apache.catalina.filters.ExpiresFilter init
* FINE: Filter initialized with configuration ExpiresFilter[
* excludedResponseStatusCode=[304],
@@ -403,26 +405,25 @@ import org.apache.juli.logging.LogFactory;
* image=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]],
* text/css=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]],
* application/javascript=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]]}]
- * </pre></code>
+ * </code>
* <p>
* Sample of per-request log message where {@code ExpiresFilter} adds an
* expiration date
* </p>
*
- * <code><pre>
+ * <code>
* Mar 26, 2010 2:09:47 PM org.apache.catalina.filters.ExpiresFilter onBeforeWriteResponseBody
* FINE: Request "/tomcat.gif" with response status "200" content-type "image/gif", set expiration date 3/26/10 2:19 PM
- * </pre></code>
+ * </code>
* <p>
* Sample of per-request log message where {@code ExpiresFilter} does not add
* an expiration date
* </p>
*
- * <code><pre>
+ * <code>
* Mar 26, 2010 2:10:27 PM org.apache.catalina.filters.ExpiresFilter onBeforeWriteResponseBody
* FINE: Request "/docs/config/manager.html" with response status "200" content-type "text/html", no expiration configured
- * </pre></code>
- *
+ * </code>
*/
public class ExpiresFilter extends FilterBase {
@@ -1065,6 +1066,7 @@ public class ExpiresFilter extends FilterBase {
/**
* Convert a given comma delimited list of strings into an array of String
*
+ * @param commaDelimitedStrings the string to be split
* @return array of patterns (non {@code null})
*/
protected static String[] commaDelimitedListToStringArray(
@@ -1074,8 +1076,10 @@ public class ExpiresFilter extends FilterBase {
}
/**
- * Return {@code true} if the given {@code str} contains the given
+ * @return {@code true} if the given {@code str} contains the given
* {@code searchStr}.
+ * @param str String that will be searched
+ * @param searchStr The substring to search
*/
protected static boolean contains(String str, String searchStr) {
if (str == null || searchStr == null) {
@@ -1086,6 +1090,8 @@ public class ExpiresFilter extends FilterBase {
/**
* Convert an array of ints into a comma delimited string
+ * @param ints The int array
+ * @return a comma separated string
*/
protected static String intsToCommaDelimitedString(int[] ints) {
if (ints == null) {
@@ -1104,7 +1110,8 @@ public class ExpiresFilter extends FilterBase {
}
/**
- * Return {@code true} if the given {@code str} is
+ * @param str The String to check
+ * @return {@code true} if the given {@code str} is
* {@code null} or has a zero characters length.
*/
protected static boolean isEmpty(String str) {
@@ -1112,7 +1119,8 @@ public class ExpiresFilter extends FilterBase {
}
/**
- * Return {@code true} if the given {@code str} has at least one
+ * @param str The String to check
+ * @return {@code true} if the given {@code str} has at least one
* character (can be a withespace).
*/
protected static boolean isNotEmpty(String str) {
@@ -1120,7 +1128,7 @@ public class ExpiresFilter extends FilterBase {
}
/**
- * Return {@code true} if the given {@code string} starts with the
+ * @return {@code true} if the given {@code string} starts with the
* given {@code prefix} ignoring case.
*
* @param string
@@ -1140,7 +1148,7 @@ public class ExpiresFilter extends FilterBase {
}
/**
- * Return the subset of the given {@code str} that is before the first
+ * @return the subset of the given {@code str} that is before the first
* occurrence of the given {@code separator}. Return {@code null}
* if the given {@code str} or the given {@code separator} is
* null. Return and empty string if the {@code separator} is empty.
@@ -1234,10 +1242,15 @@ public class ExpiresFilter extends FilterBase {
* {@code protected} for extension.
* </p>
*
+ * @param response The Servlet response
+ * @return the expiration date
* @see HttpServletResponse#getContentType()
*/
protected Date getExpirationDate(XHttpServletResponse response) {
String contentType = response.getContentType();
+ if (contentType != null) {
+ contentType = contentType.toLowerCase(Locale.ENGLISH);
+ }
// lookup exact content-type match (e.g.
// "text/html; charset=iso-8859-1")
@@ -1310,6 +1323,9 @@ public class ExpiresFilter extends FilterBase {
* <p>
* {@code protected} for extension.
* </p>
+ * @param configuration The parsed expires
+ * @param response The Servlet response
+ * @return the expiration date
*/
protected Date getExpirationDate(ExpiresConfiguration configuration,
XHttpServletResponse response) {
@@ -1390,10 +1406,12 @@ public class ExpiresFilter extends FilterBase {
}
/**
- *
* <p>
* {@code protected} for extension.
* </p>
+ * @param request The Servlet request
+ * @param response The Servlet response
+ * @return <code>true</code> if an expire header may be added
*/
protected boolean isEligibleToExpirationHeaderGeneration(
HttpServletRequest request, XHttpServletResponse response) {
@@ -1442,6 +1460,8 @@ public class ExpiresFilter extends FilterBase {
* {@link HttpServletResponse#getContentType()} costs {@code String}
* objects instantiations (as of Tomcat 7).
* </p>
+ * @param request The Servlet request
+ * @param response The Servlet response
*/
public void onBeforeWriteResponseBody(HttpServletRequest request,
XHttpServletResponse response) {
@@ -1483,7 +1503,8 @@ public class ExpiresFilter extends FilterBase {
* '{@code access plus 1 month 15 days 2 hours}' or
* '{@code modification 1 day 2 hours 5 seconds}'
*
- * @param inputLine
+ * @param inputLine the input
+ * @return the parsed expires
*/
protected ExpiresConfiguration parseExpiresConfiguration(String inputLine) {
String line = inputLine.trim();
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org