infernap12/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2026-03-14 18:03:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

8253473: Javadoc clean up in HttpHandler, HttpPrincipal, HttpContext, and HttpsConfigurator

Browse Source 
Reviewed-by: dfuchs
This commit is contained in:
Patrick Concannon 2020-10-30 08:42:20 +00:00
parent 379ba80eb7
commit d12819158a
4 changed files with 130 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpContext.java
View File

@ -28,15 +28,18 @@ import java.util.List;
import java.util.Map;
/**
* HttpContext represents a mapping between the root URI path of an application
* to a {@link HttpHandler} which is invoked to handle requests destined
* for that path on the associated HttpServer or HttpsServer.
* <p>
* HttpContext instances are created by the create methods in HttpServer
* and HttpsServer
* <p>
* A chain of {@link Filter} objects can be added to a HttpContext. All exchanges processed by the
* context can be pre- and post-processed by each Filter in the chain.
* {@code HttpContext} represents a mapping between the root {@link java.net.URI}
* path of an application to a {@link HttpHandler} which is invoked to handle
* requests destined for that path on the associated {@link HttpServer} or
* {@link HttpsServer}.
*
* <p> {@code HttpContext} instances are created by the create methods in
* {@code HttpServer} and {@code HttpsServer}.
*
* <p> A chain of {@link Filter} objects can be added to a {@code HttpContext}.
* All exchanges processed by the context can be pre- and post-processed by each
* {@code Filter} in the chain.
*
* @since 1.6
*/
public abstract class HttpContext {
@ -44,73 +47,79 @@ public abstract class HttpContext {
/**
* Constructor for subclasses to call.
*/
protected HttpContext () {
protected HttpContext() {
}
/**
* returns the handler for this context
* @return the HttpHandler for this context
* Returns the handler for this context.
*
* @return the {@code HttpHandler} for this context
*/
public abstract HttpHandler getHandler () ;
public abstract HttpHandler getHandler();
/**
* Sets the handler for this context, if not already set.
* @param h the handler to set for this context
* @throws IllegalArgumentException if this context's handler is already set.
* @throws NullPointerException if handler is <code>null</code>
*/
public abstract void setHandler (HttpHandler h) ;
/**
* returns the path this context was created with
* @return this context's path
*/
public abstract String getPath() ;
/**
* returns the server this context was created with
* @return this context's server
*/
public abstract HttpServer getServer () ;
/**
* returns a mutable Map, which can be used to pass
* configuration and other data to Filter modules
* and to the context's exchange handler.
* <p>
* Every attribute stored in this Map will be visible to
* every HttpExchange processed by this context
*
* @return a map containing the attributes of this context
* @param handler the handler to set for this context
* @throws IllegalArgumentException if the context for this handler is already set.
* @throws NullPointerException if handler is {@code null}
*/
public abstract void setHandler(HttpHandler handler);
/**
* Returns the path this context was created with.
*
* @return the context of this path
*/
public abstract String getPath();
/**
* Returns the server this context was created with.
*
* @return the context of this server
*/
public abstract HttpServer getServer();
/**
* Returns a mutable {@link Map}, which can be used to pass configuration
* and other data to {@link Filter} modules and to the context's exchange
* handler.
*
* <p> Every attribute stored in this {@code Map} will be visible to every
* {@code HttpExchange} processed by this context.
*
* @return a {@code Map} containing the attributes of this context
*/
public abstract Map<String,Object> getAttributes() ;
/**
* returns this context's list of Filters. This is the
* actual list used by the server when dispatching requests
* so modifications to this list immediately affect the
* the handling of exchanges.
* Returns this context's {@link List} of {@linkplain Filter filters}. This
* is the actual list used by the server when dispatching requests so
* modifications to this list immediately affect the the handling of exchanges.
*
* @return a {@link List} containing the filters of this context
*/
public abstract List<Filter> getFilters();
/**
* Sets the Authenticator for this HttpContext. Once an authenticator
* is establised on a context, all client requests must be
* authenticated, and the given object will be invoked to validate each
* request. Each call to this method replaces any previous value set.
* @param auth the authenticator to set. If <code>null</code> then any
* previously set authenticator is removed,
* and client authentication will no longer be required.
* @return the previous Authenticator, if any set, or <code>null</code>
* otherwise.
* Sets the {@link Authenticator} for this {@code HttpContext}. Once an authenticator
* is establised on a context, all client requests must be authenticated,
* and the given object will be invoked to validate each request. Each call
* to this method replaces any previous value set.
*
* @param auth the {@code Authenticator} to set. If {@code null} then any previously
* set {@code Authenticator} is removed, and client authentication
* will no longer be required.
* @return the previous {@code Authenticator}, if any set, or {@code null} otherwise.
*/
public abstract Authenticator setAuthenticator (Authenticator auth);
public abstract Authenticator setAuthenticator(Authenticator auth);
/**
* Returns the currently set Authenticator for this context
* Returns the currently set {@link Authenticator} for this context
* if one exists.
* @return this HttpContext's Authenticator, or <code>null</code>
* if none is set.
*
* @return this {@linkplain HttpContext HttpContext's} {@code Authenticator},
* or {@code null} if none is set
*/
public abstract Authenticator getAuthenticator ();
public abstract Authenticator getAuthenticator();
}

6
src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpHandler.java
View File

@ -30,6 +30,7 @@ import java.io.IOException;
/**
* A handler which is invoked to process HTTP exchanges. Each
* HTTP exchange is handled by one of these handlers.
*
* @since 1.6
*/
public interface HttpHandler {
@ -37,9 +38,10 @@ public interface HttpHandler {
* Handle the given request and generate an appropriate response.
* See {@link HttpExchange} for a description of the steps
* involved in handling an exchange.
*
* @param exchange the exchange containing the request from the
* client and used to send the response
* @throws NullPointerException if exchange is <code>null</code>
* client and used to send the response
* @throws NullPointerException if exchange is {@code null}
*/
public abstract void handle (HttpExchange exchange) throws IOException;
}

50
src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpPrincipal.java
View File

@ -34,12 +34,14 @@ public class HttpPrincipal implements Principal {
private String username, realm;
/**
* creates a HttpPrincipal from the given username and realm
* @param username The name of the user within the realm
* @param realm The realm.
* @throws NullPointerException if either username or realm are null
* Creates a {@code HttpPrincipal} from the given {@code username} and
* {@code realm}.
*
* @param username the name of the user within the realm
* @param realm the realm for this user
* @throws NullPointerException if either username or realm are {@code null}
*/
public HttpPrincipal (String username, String realm) {
public HttpPrincipal(String username, String realm) {
if (username == null || realm == null) {
throw new NullPointerException();
}
@ -48,12 +50,16 @@ public class HttpPrincipal implements Principal {
}
/**
* Compares two HttpPrincipal. Returns <code>true</code>
* if <i>another</i> is an instance of HttpPrincipal, and its
* username and realm are equal to this object's username
* and realm. Returns <code>false</code> otherwise.
* Compare two instances of {@code HttpPrincipal}. Returns {@code true} if
* <i>another</i> is an instance of {@code HttpPrincipal}, and its username
* and realm are equal to this object's username and realm. Returns {@code false}
* otherwise.
*
* @param another the object to compare this instance of {@code HttpPrincipal} against
* @return {@code true} or {@code false} depending on whether objects are
* equal or not
*/
public boolean equals (Object another) {
public boolean equals(Object another) {
if (!(another instanceof HttpPrincipal)) {
return false;
}
@ -63,41 +69,47 @@ public class HttpPrincipal implements Principal {
}
/**
* returns the contents of this principal in the form
* <i>realm:username</i>
* Returns the contents of this principal in the form
* <i>realm:username</i>.
*
* @return the contents of this principal in the form realm:username
*/
public String getName() {
return username;
}
/**
* returns the username this object was created with.
* Returns the {@code username} this object was created with.
*
* @return The name of the user assoicated with this object
* @return the name of the user associated with this object
*/
public String getUsername() {
return username;
}
/**
* returns the realm this object was created with.
* Returns the {@code realm} this object was created with.
*
* @return The realm associated with this object
* @return the realm associated with this object
*/
public String getRealm() {
return realm;
}
/**
* returns a hashcode for this HttpPrincipal. This is calculated
* as <code>(getUsername()+getRealm().hashCode()</code>
* Returns a hashcode for this {@code HttpPrincipal}. This is calculated
* as {@code (getUsername()+getRealm()).hashCode()}.
*
* @return the hashcode for this object
*/
public int hashCode() {
return (username+realm).hashCode();
}
/**
* returns the same string as getName()
* Returns the same string as {@link #getName()}.
*
* @return the name associated with this object
*/
public String toString() {
return getName();

62
src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsConfigurator.java
View File

@ -25,23 +25,17 @@
package com.sun.net.httpserver;
import java.net.*;
import java.io.*;
import java.nio.*;
import java.security.*;
import java.nio.channels.*;
import java.util.*;
import java.util.concurrent.*;
import javax.net.ssl.*;
import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLParameters;
/**
* This class is used to configure the https parameters for each incoming
* https connection on a HttpsServer. Applications need to override
* https connection on a {@link HttpsServer}. Applications need to override
* the {@link #configure(HttpsParameters)} method in order to change
* the default configuration.
* <p>
* The following <a id="example">example</a> shows how this may be done:
*
* <p> The following <a id="example">example</a> shows how this may be done:
*
* <blockquote><pre>
* SSLContext sslContext = SSLContext.getInstance (....);
@ -65,6 +59,7 @@ import javax.net.ssl.*;
* }
* });
* </pre></blockquote>
*
* @since 1.6
*/
public class HttpsConfigurator {
@ -72,11 +67,12 @@ public class HttpsConfigurator {
private SSLContext context;
/**
* Creates an Https configuration, with the given SSLContext.
* @param context the SSLContext to use for this configurator
* @throws NullPointerException if no SSLContext supplied
* Creates a Https configuration, with the given {@link SSLContext}.
*
* @param context the {@code SSLContext} to use for this configurator
* @throws NullPointerException if no {@code SSLContext} supplied
*/
public HttpsConfigurator (SSLContext context) {
public HttpsConfigurator(SSLContext context) {
if (context == null) {
throw new NullPointerException ("null SSLContext");
}
@ -84,33 +80,33 @@ public class HttpsConfigurator {
}
/**
* Returns the SSLContext for this HttpsConfigurator.
* @return the SSLContext
* Returns the {@link SSLContext} for this {@code HttpsConfigurator}.
*
* @return the {@code SSLContext}
*/
public SSLContext getSSLContext() {
return context;
}
//BEGIN_TIGER_EXCLUDE
/**
* Called by the HttpsServer to configure the parameters
* for a https connection currently being established.
* The implementation of configure() must call
* {@link HttpsParameters#setSSLParameters(SSLParameters)}
* in order to set the SSL parameters for the connection.
* <p>
* The default implementation of this method uses the
* SSLParameters returned from <p>
* {@code getSSLContext().getDefaultSSLParameters()}
* <p>
* configure() may be overridden in order to modify this behavior.
* See, the example <a href="#example">above</a>.
* @param params the HttpsParameters to be configured.
* Called by the {@link HttpsServer} to configure the parameters for a https
* connection currently being established. The implementation of configure()
* must call {@link HttpsParameters#setSSLParameters(SSLParameters)} in order
* to set the SSL parameters for the connection.
*
* <p> The default implementation of this method uses the
* SSLParameters returned from:
*
* <p> {@code getSSLContext().getDefaultSSLParameters()}
*
* <p> configure() may be overridden in order to modify this behavior. See
* example <a href="#example">above</a>.
*
* @param params the {@code HttpsParameters} to be configured
*
* @since 1.6
*/
public void configure (HttpsParameters params) {
public void configure(HttpsParameters params) {
params.setSSLParameters (getSSLContext().getDefaultSSLParameters());
}
//END_TIGER_EXCLUDE
}