stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8253470: Javadoc clean up in Filter and Headers

Browse Source 
Reviewed-by: dfuchs, michaelm
This commit is contained in:
Patrick Concannon 2020-10-02 12:06:48 +00:00
parent f686a380f3
commit 0fd41c3b6a
2 changed files with 109 additions and 82 deletions
src/jdk.httpserver/share/classes/com/sun/net/httpserver
Filter.javaHeaders.java

105
src/jdk.httpserver/share/classes/com/sun/net/httpserver/Filter.java

@ -26,17 +26,21 @@
package com.sun.net.httpserver;
import java.io.IOException;
import java.util.*;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.List;
import java.util.ListIterator;
/**
* A filter used to pre- and post-process incoming requests. Pre-processing occurs
* before the application's exchange handler is invoked, and post-processing
* occurs after the exchange handler returns. Filters
* are organised in chains, and are associated with HttpContext instances.
* <p>
* Each Filter in the chain, invokes the next filter within its own
* doFilter() implementation. The final Filter in the chain invokes the applications
* exchange handler.
* occurs after the exchange handler returns. Filters are organised in chains,
* and are associated with {@link HttpContext} instances.
*
* <p> Each {@code Filter} in the chain, invokes the next filter within its own
* {@link #doFilter(HttpExchange, Chain)} implementation. The final {@code Filter}
* in the chain invokes the applications exchange handler.
*
* @since 1.6
*/
public abstract class Filter {
@ -47,13 +51,15 @@ public abstract class Filter {
protected Filter () {}
/**
* a chain of filters associated with a HttpServer.
* Each filter in the chain is given one of these
* so it can invoke the next filter in the chain
* A chain of filters associated with a {@link HttpServer}.
* Each filter in the chain is given one of these so it can invoke the
* next filter in the chain.
*/
public static class Chain {
/* the last element in the chain must invoke the users
* handler
/**
* The last element in the chain must invoke the user's
* handler.
*/
private ListIterator<Filter> iter;
private HttpHandler handler;
@ -61,9 +67,9 @@ public abstract class Filter {
/**
* Creates a {@code Chain} instance with given filters and handler.
*
* @param filters The filters that make up the Chain
* @param handler The HttpHandler that will be invoked after the final
* Filter has finished
* @param filters the filters that make up the {@code Chain}
* @param handler the {@link HttpHandler} that will be invoked after
* the final {@code Filter} has finished
*/
public Chain (List<Filter> filters, HttpHandler handler) {
iter = filters.listIterator();
@ -71,15 +77,15 @@ public abstract class Filter {
}
/**
* calls the next filter in the chain, or else
* the users exchange handler, if this is the
* final filter in the chain. The Filter may decide
* to terminate the chain, by not calling this method.
* In this case, the filter <b>must</b> send the
* response to the request, because the application's
* exchange handler will not be invoked.
* @param exchange the HttpExchange
* @throws IOException let exceptions pass up the stack
* Calls the next filter in the chain, or else the users exchange
* handler, if this is the final filter in the chain. The {@code Filter}
* may decide to terminate the chain, by not calling this method.
* In this case, the filter <b>must</b> send the response to the
* request, because the application's {@linkplain HttpExchange exchange}
* handler will not be invoked.
*
* @param exchange the {@code HttpExchange}
* @throws IOException if an I/O error occurs
* @throws NullPointerException if exchange is {@code null}
*/
public void doFilter (HttpExchange exchange) throws IOException {
@ -95,35 +101,42 @@ public abstract class Filter {
/**
* Asks this filter to pre/post-process the given exchange. The filter
* can:
* <ul><li>examine or modify the request headers</li>
* <li>filter the request body or the response body, by creating suitable
* filter streams and calling
* {@link HttpExchange#setStreams(InputStream,OutputStream)}</li>
* <li>set attribute Objects in the exchange, which other filters or the
* exchange handler can access.</li>
* <li>decide to either<ol>
* <li>invoke the next filter in the chain, by calling
* {@link Filter.Chain#doFilter(HttpExchange)}</li>
* <li>terminate the chain of invocation, by <b>not</b> calling
* {@link Filter.Chain#doFilter(HttpExchange)}</li></ol>
* <li>if option 1. above taken, then when doFilter() returns all subsequent
* filters in the Chain have been called, and the response headers can be
* examined or modified.</li>
* <li>if option 2. above taken, then this Filter must use the HttpExchange
* to send back an appropriate response</li></ul>
*
* @param exchange the {@code HttpExchange} to be filtered.
* @param chain the Chain which allows the next filter to be invoked.
* @throws IOException may be thrown by any filter module, and if
* caught, must be rethrown again.
* <ul>
* <li> Examine or modify the request headers.
* <li> Filter the request body or the response body, by creating suitable
* filter streams and calling {@link HttpExchange#setStreams(InputStream, OutputStream)}.
* <li> Set attribute objects in the exchange, which other filters or
* the exchange handler can access.
* <li> Decide to either:
*
* <ol>
* <li> Invoke the next filter in the chain, by calling
* {@link Filter.Chain#doFilter(HttpExchange)}.
* <li> Terminate the chain of invocation, by <b>not</b> calling
* {@link Filter.Chain#doFilter(HttpExchange)}.
* </ol>
*
* <li> If option 1. above is taken, then when doFilter() returns all subsequent
* filters in the Chain have been called, and the response headers can be
* examined or modified.
* <li> If option 2. above is taken, then this Filter must use the HttpExchange
* to send back an appropriate response.
* </ul>
*
* @param exchange the {@code HttpExchange} to be filtered
* @param chain the {@code Chain} which allows the next filter to be invoked
* @throws IOException may be thrown by any filter module, and if caught,
* must be rethrown again
* @throws NullPointerException if either exchange or chain are {@code null}
*/
public abstract void doFilter (HttpExchange exchange, Chain chain)
throws IOException;
/**
* returns a short description of this Filter
* @return a string describing the Filter
* Returns a short description of this {@code Filter}.
*
* @return a {@code String} describing the {@code Filter}
*/
public abstract String description ();

86
src/jdk.httpserver/share/classes/com/sun/net/httpserver/Headers.java

@ -25,40 +25,52 @@
package com.sun.net.httpserver;
import java.util.*;
import java.util.Collection;
import java.util.HashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* HTTP request and response headers are represented by this class which implements
* the interface
* {@link java.util.Map}{@literal <}{@link java.lang.String}, {@link java.util.List}
* {@literal <}{@link java.lang.String}{@literal >>}.
* HTTP request and response headers are represented by this class which
* implements the interface
* {@link java.util.Map}{@literal <}{@link java.lang.String},
* {@link java.util.List} {@literal <}{@link java.lang.String}{@literal >>}.
* The keys are case-insensitive Strings representing the header names and
* the value associated with each key is
* a {@link List}{@literal <}{@link String}{@literal >} with one
* element for each occurrence of the header name in the request or response.
* <p>
* For example, if a response header instance contains
*
* <p> For example, if a response header instance contains
* one key "HeaderName" with two values "value1 and value2"
* then this object is output as two header lines:
*
* <blockquote><pre>
* HeaderName: value1
* HeaderName: value2
* </pre></blockquote>
* <p>
* All the normal {@link java.util.Map} methods are provided, but the following
* additional convenience methods are most likely to be used:
*
* All the normal {@link java.util.Map} methods are provided, but the
* following additional convenience methods are most likely to be used:
*
* <ul>
* <li>{@link #getFirst(String)} returns a single valued header or the first value of
* a multi-valued header.</li>
* <li>{@link #add(String,String)} adds the given header value to the list for the given key</li>
* <li>{@link #set(String,String)} sets the given header field to the single value given
* overwriting any existing values in the value list.
* </ul><p>
* All methods in this class accept <code>null</code> values for keys and values. However, null
* keys will never will be present in HTTP request headers, and will not be output/sent in response headers.
* Null values can be represented as either a null entry for the key (i.e. the list is null) or
* where the key has a list, but one (or more) of the list's values is null. Null values are output
* as a header line containing the key but no associated value.
* <li>{@link #getFirst(String)} returns a single valued header or the first
* value of a multi-valued header.
* <li>{@link #add(String,String)} adds the given header value to the list
* for the given key.
* <li>{@link #set(String,String)} sets the given header field to the single
* value given overwriting any existing values in the value list.
* </ul>
*
* <p> All methods in this class accept {@code null} values for keys and values.
* However, {@code null} keys will never will be present in HTTP request
* headers, and will not be output/sent in response headers. Null values can be
* represented as either a {@code null} entry for the key (i.e. the list is
* {@code null}) or where the key has a list, but one (or more) of the list's
* values is {@code null}. Null values are output as a header line containing
* the key but no associated value.
*
* @since 1.6
*/
public class Headers implements Map<String,List<String>> {
@ -66,13 +78,14 @@ public class Headers implements Map<String,List<String>> {
HashMap<String,List<String>> map;
/**
* Creates an empty instance of Headers.
* Creates an empty instance of {@code Headers}.
*/
public Headers () {map = new HashMap<String,List<String>>(32);}
/* Normalize the key by converting to following form.
* First char upper case, rest lower case.
* key is presumed to be ASCII
/**
* Normalize the key by converting to following form.
* First {@code char} upper case, rest lower case.
* key is presumed to be {@code ASCII}.
*/
private String normalize (String key) {
if (key == null) {
@ -120,10 +133,11 @@ public class Headers implements Map<String,List<String>> {
}
/**
* returns the first value from the List of String values
* for the given key (if at least one exists).
* Returns the first value from the {@link List} of {@code String}
* values for the given key (if at least one exists).
*
* @param key the key to search for
* @return the first string value associated with the key
* @return the first {@code String} value associated with the key
*/
public String getFirst (String key) {
List<String> l = map.get(normalize(key));
@ -140,11 +154,11 @@ public class Headers implements Map<String,List<String>> {
}
/**
* adds the given value to the list of headers
* for the given key. If the mapping does not
* already exist, then it is created
* Adds the given value to the list of headers for the given key. If
* the mapping does not already exist, then it is created.
*
* @param key the header name
* @param value the header value to add to the header
* @param value the value to add to the header
*/
public void add (String key, String value) {
checkValue(value);
@ -182,11 +196,11 @@ public class Headers implements Map<String,List<String>> {
}
/**
* sets the given value as the sole header value
* for the given key. If the mapping does not
* already exist, then it is created
* Sets the given value as the sole header value for the given
* key. If the mapping does not already exist, then it is created.
*
* @param key the header name
* @param value the header value to set.
* @param value the header value to set
*/
public void set (String key, String value) {
LinkedList<String> l = new LinkedList<String>();