Skip to content

Commit

Permalink
Fixes #368 Updates javadoc for getRemoteAddr
Browse files Browse the repository at this point in the history 
Fixes #368 with javadoc updates for:
 + reference to RFC 7239  for obtaining local/remote IP and ports
 + removed historic references to CGI variables
 + relaxed the dependence on the host header, which may not be present in HTTP/2
  • Loading branch information
@gregw
gregw committed Oct 12, 2020
1 parent 0a138d1 commit 29308d1
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 37 deletions.
60 changes: 35 additions & 25 deletions api/src/main/java/jakarta/servlet/ServletRequest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ public interface ServletRequest {

/**
* Returns the length, in bytes, of the request body and made available by the input stream, or -1 if the length is not
* known or is greater than Integer.MAX_VALUE. For HTTP servlets, same as the value of the CGI variable CONTENT_LENGTH.
* known or is greater than Integer.MAX_VALUE.
*
* @return an integer containing the length of the request body or -1 if the length is not known or is greater than
* Integer.MAX_VALUE.
Expand All @@ -101,7 +101,7 @@ public interface ServletRequest {

/**
* Returns the length, in bytes, of the request body and made available by the input stream, or -1 if the length is not
* known. For HTTP servlets, same as the value of the CGI variable CONTENT_LENGTH.
* known.
*
* @return a long containing the length of the request body or -1L if the length is not known
*
Expand All @@ -110,8 +110,7 @@ public interface ServletRequest {
public long getContentLengthLong();

/**
* Returns the MIME type of the body of the request, or <code>null</code> if the type is not known. For HTTP servlets,
* same as the value of the CGI variable CONTENT_TYPE.
* Returns the MIME type of the body of the request, or <code>null</code> if the type is not known.
*
* @return a <code>String</code> containing the name of the MIME type of the request, or null if the type is not known
*/
Expand Down Expand Up @@ -193,8 +192,7 @@ public interface ServletRequest {

/**
* Returns the name and version of the protocol the request uses in the form <i>protocol/majorVersion.minorVersion</i>,
* for example, HTTP/1.1. For HTTP servlets, the value returned is the same as the value of the CGI variable
* <code>SERVER_PROTOCOL</code>.
* for example, HTTP/1.1.
*
* @return a <code>String</code> containing the protocol name and version number
*/
Expand All @@ -209,16 +207,19 @@ public interface ServletRequest {
public String getScheme();

/**
* Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the
* <code>Host</code> header value, if any, or the resolved server name, or the server IP address.
* Returns the host name of the server to which the request was sent. It may be derived from a protocol specific
* mechanism, such as the <code>Host</code> header, or the HTTP/2 authority,
* or <a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a>, otherwise the
* resolved server name or the server IP address.
*
* @return a <code>String</code> containing the name of the server
*/
public String getServerName();

/**
* Returns the port number to which the request was sent. It is the value of the part after ":" in the <code>Host</code>
* header value, if any, or the server port where the client connection was accepted on.
* Returns the port number to which the request was sent. It may be derived from a protocol specific mechanism, such as
* the <code>Host</code> header, or HTTP authority, or <a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a>,
* otherwise the server port where the client connection was accepted on.
*
* @return an integer specifying the port number
*/
Expand All @@ -243,19 +244,20 @@ public interface ServletRequest {
public BufferedReader getReader() throws IOException;

/**
* Returns the Internet Protocol (IP) address of the client or last proxy that sent the request. For HTTP servlets, same
* as the value of the CGI variable <code>REMOTE_ADDR</code>.
* Returns the Internet Protocol (IP) of the remote end of the connection on which the request was received. By default
* this is either the address of the client or last proxy that sent the request. In some cases a protocol specific
* mechanism, such as <a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a>, may be used to obtain an address
* different to that of the actual TCP/IP connection.
*
* @return a <code>String</code> containing the IP address of the client that sent the request
* @return a <code>String</code> containing an IP address
*/
public String getRemoteAddr();

/**
* Returns the fully qualified name of the client or the last proxy that sent the request. If the engine cannot or
* chooses not to resolve the hostname (to improve performance), this method returns the dotted-string form of the IP
* address. For HTTP servlets, same as the value of the CGI variable <code>REMOTE_HOST</code>.
* Returns the fully qualified name of the address returned by {@link #getRemoteAddr()}. If the engine cannot or chooses
* not to resolve the hostname (to improve performance), this method returns the IP address.
*
* @return a <code>String</code> containing the fully qualified name of the client
* @return a <code>String</code> containing a fully qualified name or IP address.
*/
public String getRemoteHost();

Expand Down Expand Up @@ -359,7 +361,10 @@ public interface ServletRequest {
public String getRealPath(String path);

/**
* Returns the Internet Protocol (IP) source port of the client or last proxy that sent the request.
* Returns the Internet Protocol (IP) source port the remote end of the connection on which the request was received. By
* default this is either the port of the client or last proxy that sent the request. In some cases, protocol specific
* mechanisms such as <a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a> may be used to obtain a port different
* to that of the actual TCP/IP connection.
*
* @return an integer specifying the port number
*
Expand All @@ -368,27 +373,32 @@ public interface ServletRequest {
public int getRemotePort();

/**
* Returns the host name of the Internet Protocol (IP) interface on which the request was received.
*
* Returns the fully qualified name of the address returned by {@link #getLocalAddr()}. If the engine cannot or chooses
* not to resolve the hostname (to improve performance), this method returns the IP address.
*
* @return a <code>String</code> containing the host name of the IP on which the request was received.
*
* @since Servlet 2.4
*/
public String getLocalName();

/**
* Returns the Internet Protocol (IP) address of the interface on which the request was received.
*
* @return a <code>String</code> containing the IP address on which the request was received.
* Returns the Internet Protocol (IP) address representing the interface on which the request was received. In some
* cases a protocol specific mechanism, such as <a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a>, may be used
* to obtain an address different to that of the actual TCP/IP connection.
*
* @return a <code>String</code> containing an IP address.
*
* @since Servlet 2.4
*/
public String getLocalAddr();

/**
* Returns the Internet Protocol (IP) port number of the interface on which the request was received.
* Returns the Internet Protocol (IP) port number representing the interface on which the request was received. In some
* cases, a protocol specific mechanism such as <a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a> may be used
* to obtain an address different to that of the actual TCP/IP connection.
*
* @return an integer specifying the port number
* @return an integer specifying a port number
*
* @since Servlet 2.4
*/
Expand Down
16 changes: 4 additions & 12 deletions api/src/main/java/jakarta/servlet/http/HttpServletRequest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,6 @@ public interface HttpServletRequest extends ServletRequest {
* and client certificate authentication, and may additionally support digest authentication. If the servlet is not
* authenticated <code>null</code> is returned.
*
* <p>
* Same as the value of the CGI variable AUTH_TYPE.
*
* @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH (suitable for == comparison)
* or the container-specific string indicating the authentication scheme, or <code>null</code> if the request was not
* authenticated.
Expand Down Expand Up @@ -239,8 +236,7 @@ public String toString() {
}

/**
* Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT. Same as the
* value of the CGI variable REQUEST_METHOD.
* Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.
*
* @return a <code>String</code> specifying the name of the method with which this request was made
*/
Expand All @@ -253,9 +249,6 @@ public String toString() {
* <p>
* This method returns <code>null</code> if there was no extra path information.
*
* <p>
* Same as the value of the CGI variable PATH_INFO.
*
* @return a <code>String</code>, decoded by the web container, specifying extra path information that comes after the
* servlet path but before the query string in the request URL; or <code>null</code> if the URL does not have any extra
* path information
Expand All @@ -264,7 +257,7 @@ public String toString() {

/**
* Returns any extra path information after the servlet name but before the query string, and translates it to a real
* path. Same as the value of the CGI variable PATH_TRANSLATED.
* path.
*
* <p>
* If the URL does not have any extra path information, this method returns <code>null</code> or the servlet container
Expand Down Expand Up @@ -314,7 +307,7 @@ default public PushBuilder newPushBuilder() {

/**
* Returns the query string that is contained in the request URL after the path. This method returns <code>null</code>
* if the URL does not have a query string. Same as the value of the CGI variable QUERY_STRING.
* if the URL does not have a query string.
*
* @return a <code>String</code> containing the query string or <code>null</code> if the URL contains no query string.
* The value is not decoded by the container.
Expand All @@ -324,7 +317,7 @@ default public PushBuilder newPushBuilder() {
/**
* Returns the login of the user making this request, if the user has been authenticated, or <code>null</code> if the
* user has not been authenticated. Whether the user name is sent with each subsequent request depends on the browser
* and type of authentication. Same as the value of the CGI variable REMOTE_USER.
* and type of authentication.
*
* @return a <code>String</code> specifying the login of the user making this request, or <code>null</code> if the user
* login is not known
Expand Down Expand Up @@ -425,7 +418,6 @@ default public PushBuilder newPushBuilder() {
/**
* Returns the part of this request's URL that calls the servlet. This path starts with a "/" character and includes
* either the servlet name or a path to the servlet, but does not include any extra path information or a query string.
* Same as the value of the CGI variable SCRIPT_NAME.
*
* <p>
* This method will return an empty string ("") if the servlet used to process this request was matched using the "/*"
Expand Down

0 comments on commit 29308d1

Please sign in to comment.