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 b5beb7be415e7ea0ea03b007f5d94c42dbe80c01
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Tue Jul 9 15:55:22 2019 +0100
Javadoc updates to align with 8.5.x
---
.../apache/catalina/filters/RemoteIpFilter.java | 75 +++++++++++++---------
1 file changed, 43 insertions(+), 32 deletions(-)
diff --git a/java/org/apache/catalina/filters/RemoteIpFilter.java
b/java/org/apache/catalina/filters/RemoteIpFilter.java
index d52bba9..1bc5b9f 100644
--- a/java/org/apache/catalina/filters/RemoteIpFilter.java
+++ b/java/org/apache/catalina/filters/RemoteIpFilter.java
@@ -67,6 +67,7 @@ import org.apache.juli.logging.LogFactory;
* <p>
* If the incoming <code>request.getRemoteAddr()</code> matches the servlet
* filter's list of internal or trusted proxies:
+ * </p>
* <ul>
* <li>Loop on the comma delimited list of IPs and hostnames passed by the
preceding load balancer or proxy in the given request's Http
* header named <code>$remoteIpHeader</code> (default value
<code>x-forwarded-for</code>). Values are processed in right-to-left order.</li>
@@ -82,10 +83,8 @@ import org.apache.juli.logging.LogFactory;
* <code>request.scheme = https</code> and <code>request.serverPort =
443</code>. Note that 443 can be overwritten with the
* <code>$httpsServerPort</code> configuration parameter.</li>
* </ul>
- * </p>
- * <p>
- * <strong>Configuration parameters:</strong>
* <table border="1">
+ * <caption>Configuration parameters</caption>
* <tr>
* <th>XForwardedFilter property</th>
* <th>Description</th>
@@ -164,8 +163,6 @@ import org.apache.juli.logging.LogFactory;
* <td>443</td>
* </tr>
* </table>
- * </p>
- * <p>
* <p>
* <strong>Regular expression vs. IP address blocks:</strong>
<code>mod_remoteip</code> allows to use address blocks (e.g.
* <code>192.168/16</code>) to configure <code>RemoteIPInternalProxy</code>
and <code>RemoteIPTrustedProxy</code> ; as the JVM doesn't have a
@@ -173,14 +170,14 @@ import org.apache.juli.logging.LogFactory;
*
href="https://apr.apache.org/docs/apr/1.3/group__apr__network__io.html#gb74d21b8898b7c40bf7fd07ad3eb993d";>apr_ipsubnet_test</a>,
we rely on
* regular expressions.
* </p>
- * <hr/>
+ * <hr>
* <p>
* <strong>Sample with internal proxies</strong>
* </p>
* <p>
* XForwardedFilter configuration:
* </p>
- * <code><pre>
+ * <code>
* <filter>
* <filter-name>RemoteIpFilter</filter-name>
*
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
@@ -206,10 +203,9 @@ import org.apache.juli.logging.LogFactory;
* <filter-name>RemoteIpFilter</filter-name>
* <url-pattern>/*</url-pattern>
* <dispatcher>REQUEST</dispatcher>
- * </filter-mapping></pre></code>
- * <p>
- * Request values:
+ * </filter-mapping></code>
* <table border="1">
+ * <caption>Request Values</caption>
* <tr>
* <th>property</th>
* <th>Value Before RemoteIpFilter</th>
@@ -253,15 +249,14 @@ import org.apache.juli.logging.LogFactory;
* </table>
* Note : <code>x-forwarded-by</code> header is null because only internal
proxies as been traversed by the request.
* <code>x-forwarded-by</code> is null because all the proxies are trusted or
internal.
- * </p>
- * <hr/>
+ * <hr>
* <p>
* <strong>Sample with trusted proxies</strong>
* </p>
* <p>
* RemoteIpFilter configuration:
* </p>
- * <code><pre>
+ * <code>
* <filter>
* <filter-name>RemoteIpFilter</filter-name>
*
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
@@ -287,10 +282,9 @@ import org.apache.juli.logging.LogFactory;
* <filter-name>RemoteIpFilter</filter-name>
* <url-pattern>/*</url-pattern>
* <dispatcher>REQUEST</dispatcher>
- * </filter-mapping></pre></code>
- * <p>
- * Request values:
+ * </filter-mapping></code>
* <table border="1">
+ * <caption>Request Values</caption>
* <tr>
* <th>property</th>
* <th>Value Before RemoteIpFilter</th>
@@ -312,17 +306,18 @@ import org.apache.juli.logging.LogFactory;
* <td>proxy1, proxy2</td>
* </tr>
* </table>
+ * <p>
* Note : <code>proxy1</code> and <code>proxy2</code> are both trusted proxies
that come in <code>x-forwarded-for</code> header, they both
* are migrated in <code>x-forwarded-by</code> header.
<code>x-forwarded-by</code> is null because all the proxies are trusted or
internal.
* </p>
- * <hr/>
+ * <hr>
* <p>
* <strong>Sample with internal and trusted proxies</strong>
* </p>
* <p>
* RemoteIpFilter configuration:
* </p>
- * <code><pre>
+ * <code>
* <filter>
* <filter-name>RemoteIpFilter</filter-name>
*
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
@@ -348,10 +343,9 @@ import org.apache.juli.logging.LogFactory;
* <filter-name>RemoteIpFilter</filter-name>
* <url-pattern>/*</url-pattern>
* <dispatcher>REQUEST</dispatcher>
- * </filter-mapping></pre></code>
- * <p>
- * Request values:
+ * </filter-mapping></code>
* <table border="1">
+ * <caption>Request Values</caption>
* <tr>
* <th>property</th>
* <th>Value Before RemoteIpFilter</th>
@@ -373,18 +367,19 @@ import org.apache.juli.logging.LogFactory;
* <td>proxy1, proxy2</td>
* </tr>
* </table>
+ * <p>
* Note : <code>proxy1</code> and <code>proxy2</code> are both trusted proxies
that come in <code>x-forwarded-for</code> header, they both
* are migrated in <code>x-forwarded-by</code> header. As
<code>192.168.0.10</code> is an internal proxy, it does not appear in
* <code>x-forwarded-by</code>. <code>x-forwarded-by</code> is null because
all the proxies are trusted or internal.
* </p>
- * <hr/>
+ * <hr>
* <p>
* <strong>Sample with an untrusted proxy</strong>
* </p>
* <p>
* RemoteIpFilter configuration:
* </p>
- * <code><pre>
+ * <code>
* <filter>
* <filter-name>RemoteIpFilter</filter-name>
*
<filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
@@ -410,10 +405,9 @@ import org.apache.juli.logging.LogFactory;
* <filter-name>RemoteIpFilter</filter-name>
* <url-pattern>/*</url-pattern>
* <dispatcher>REQUEST</dispatcher>
- * </filter-mapping></pre></code>
- * <p>
- * Request values:
+ * </filter-mapping></code>
* <table border="1">
+ * <caption>Request Values</caption>
* <tr>
* <th>property</th>
* <th>Value Before RemoteIpFilter</th>
@@ -435,14 +429,16 @@ import org.apache.juli.logging.LogFactory;
* <td>proxy1</td>
* </tr>
* </table>
+ * <p>
* Note : <code>x-forwarded-by</code> holds the trusted proxy
<code>proxy1</code>. <code>x-forwarded-by</code> holds
- * <code>140.211.11.130</code> because <code>untrusted-proxy</code> is not
trusted and thus, we can not trust that
+ * <code>140.211.11.130</code> because <code>untrusted-proxy</code> is not
trusted and thus, we cannot trust that
* <code>untrusted-proxy</code> is the actual remote ip.
<code>request.remoteAddr</code> is <code>untrusted-proxy</code> that is an IP
* verified by <code>proxy1</code>.
* </p>
- * <hr/>
+ * <hr>
*/
public class RemoteIpFilter implements Filter {
+
public static class XForwardedRequest extends HttpServletRequestWrapper {
static final ThreadLocal<SimpleDateFormat[]> threadLocalDateFormats =
new ThreadLocal<SimpleDateFormat[]>() {
@@ -677,6 +673,7 @@ public class RemoteIpFilter implements Filter {
/**
* Convert a given comma delimited list of regular expressions into an
array of String
*
+ * @param commaDelimitedStrings The string to split
* @return array of patterns (non <code>null</code>)
*/
protected static String[] commaDelimitedListToStringArray(String
commaDelimitedStrings) {
@@ -685,7 +682,10 @@ public class RemoteIpFilter implements Filter {
}
/**
- * Convert an array of strings in a comma delimited string
+ * Convert a list of strings in a comma delimited string.
+ *
+ * @param stringList List of strings
+ * @return concatenated string
*/
protected static String listToCommaDelimitedString(List<String>
stringList) {
if (stringList == null) {
@@ -916,6 +916,7 @@ public class RemoteIpFilter implements Filter {
/**
* Wrap the incoming <code>request</code> in a {@link XForwardedRequest}
if the http header <code>x-forwarded-for</code> is not empty.
+ * {@inheritDoc}
*/
@Override
public void doFilter(ServletRequest request, ServletResponse response,
FilterChain chain) throws IOException, ServletException {
@@ -1026,12 +1027,13 @@ public class RemoteIpFilter implements Filter {
* <p>
* If <code>true</code>, the return values for both {@link
* ServletRequest#getLocalPort()} and {@link
ServletRequest#getServerPort()}
- * wil be modified by this Filter rather than just
+ * will be modified by this Filter rather than just
* {@link ServletRequest#getServerPort()}.
* </p>
* <p>
* Default value : <code>false</code>
* </p>
+ * @param changeLocalPort The new flag value
*/
public void setChangeLocalPort(boolean changeLocalPort) {
this.changeLocalPort = changeLocalPort;
@@ -1045,6 +1047,7 @@ public class RemoteIpFilter implements Filter {
* <p>
* Default value : 80
* </p>
+ * @param httpServerPort The server port to use
*/
public void setHttpServerPort(int httpServerPort) {
this.httpServerPort = httpServerPort;
@@ -1057,6 +1060,7 @@ public class RemoteIpFilter implements Filter {
* <p>
* Default value : 443
* </p>
+ * @param httpsServerPort The server port to use
*/
public void setHttpsServerPort(int httpsServerPort) {
this.httpsServerPort = httpsServerPort;
@@ -1069,6 +1073,7 @@ public class RemoteIpFilter implements Filter {
* <p>
* Default value :
10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|169\.254.\d{1,3}.\d{1,3}|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|0:0:0:0:0:0:0:1
* </p>
+ * @param internalProxies The regexp
*/
public void setInternalProxies(String internalProxies) {
if (internalProxies == null || internalProxies.length() == 0) {
@@ -1080,13 +1085,14 @@ public class RemoteIpFilter implements Filter {
/**
* <p>
- * Header that holds the incoming port, usally named
+ * Header that holds the incoming port, usually named
* <code>X-Forwarded-Port</code>. If <code>null</code>,
* {@link #httpServerPort} or {@link #httpsServerPort} will be used.
* </p>
* <p>
* Default value : <code>null</code>
* </p>
+ * @param portHeader The header name
*/
public void setPortHeader(String portHeader) {
this.portHeader = portHeader;
@@ -1094,12 +1100,13 @@ public class RemoteIpFilter implements Filter {
/**
* <p>
- * Header that holds the incoming protocol, usally named
<code>X-Forwarded-Proto</code>. If <code>null</code>, request.scheme and
+ * Header that holds the incoming protocol, usually named
<code>X-Forwarded-Proto</code>. If <code>null</code>, request.scheme and
* request.secure will not be modified.
* </p>
* <p>
* Default value : <code>null</code>
* </p>
+ * @param protocolHeader The header name
*/
public void setProtocolHeader(String protocolHeader) {
this.protocolHeader = protocolHeader;
@@ -1112,6 +1119,7 @@ public class RemoteIpFilter implements Filter {
* <p>
* Default value : <code>https</code>
* </p>
+ * @param protocolHeaderHttpsValue The header value
*/
public void setProtocolHeaderHttpsValue(String protocolHeaderHttpsValue) {
this.protocolHeaderHttpsValue = protocolHeaderHttpsValue;
@@ -1132,6 +1140,7 @@ public class RemoteIpFilter implements Filter {
* <p>
* Default value : <code>X-Forwarded-By</code>
* </p>
+ * @param proxiesHeader The header name
*/
public void setProxiesHeader(String proxiesHeader) {
this.proxiesHeader = proxiesHeader;
@@ -1147,6 +1156,7 @@ public class RemoteIpFilter implements Filter {
* <p>
* Default value : <code>X-Forwarded-For</code>
* </p>
+ * @param remoteIpHeader The header name
*/
public void setRemoteIpHeader(String remoteIpHeader) {
this.remoteIpHeader = remoteIpHeader;
@@ -1183,6 +1193,7 @@ public class RemoteIpFilter implements Filter {
* <p>
* Default value : empty list, no external proxy is trusted.
* </p>
+ * @param trustedProxies The trusted proxies regexp
*/
public void setTrustedProxies(String trustedProxies) {
if (trustedProxies == null || trustedProxies.length() == 0) {
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
