- * HttpContext instances are created by the create methods in HttpServer - * and HttpsServer - *
- * 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}. + * + *
{@code HttpContext} instances are created by the create methods in + * {@code HttpServer} and {@code HttpsServer}. + * + *
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 null
- */
- 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.
- *
- * 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. + * + *
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
- * The following example shows how this may be done:
+ *
+ * The following example shows how this may be done:
*
*
- * The default implementation of this method uses the
- * SSLParameters returned from
- * {@code getSSLContext().getDefaultSSLParameters()}
- *
- * configure() may be overridden in order to modify this behavior.
- * See, the example above.
- * @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.
+ *
+ * The default implementation of this method uses the
+ * SSLParameters returned from:
+ *
+ * {@code getSSLContext().getDefaultSSLParameters()}
+ *
+ * configure() may be overridden in order to modify this behavior. See
+ * example above.
+ *
+ * @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
}
null then any
- * previously set authenticator is removed,
- * and client authentication will no longer be required.
- * @return the previous Authenticator, if any set, or null
- * 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 null
- * 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();
}
diff --git a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpHandler.java b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpHandler.java
index 8ea7024e686..8f54bb1530f 100644
--- a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpHandler.java
+++ b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpHandler.java
@@ -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 null
+ * client and used to send the response
+ * @throws NullPointerException if exchange is {@code null}
*/
public abstract void handle (HttpExchange exchange) throws IOException;
}
diff --git a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpPrincipal.java b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpPrincipal.java
index 863c74c9a38..43db2ab0474 100644
--- a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpPrincipal.java
+++ b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpPrincipal.java
@@ -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 true
- * if another is an instance of HttpPrincipal, and its
- * username and realm are equal to this object's username
- * and realm. Returns false otherwise.
+ * Compare two instances of {@code HttpPrincipal}. Returns {@code true} if
+ * another 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
- * realm:username
+ * Returns the contents of this principal in the form
+ * realm:username.
+ *
+ * @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 (getUsername()+getRealm().hashCode()
+ * 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();
diff --git a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsConfigurator.java b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsConfigurator.java
index dbd46a5ac5b..8cd9e3affa2 100644
--- a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsConfigurator.java
+++ b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsConfigurator.java
@@ -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.
- *
+ *
* @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.
- *
* SSLContext sslContext = SSLContext.getInstance (....);
@@ -65,6 +59,7 @@ import javax.net.ssl.*;
* }
* });
*