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

8253053: Javadoc clean up in Authenticator and BasicAuthenicator

Browse Source 
Reviewed-by: dfuchs, rriggs, chegar, michaelm
This commit is contained in:
Patrick Concannon 2020-09-28 13:17:46 +00:00
parent 840aa2b79e
commit 16b8c39964
2 changed files with 44 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
src/jdk.httpserver/share/classes/com/sun/net/httpserver/Authenticator.java
View File

@ -41,7 +41,7 @@ public abstract class Authenticator {
protected Authenticator () { }
/**
* Base class for return type from authenticate() method
* Base class for return type from {@link #authenticate(HttpExchange)} method.
*/
public abstract static class Result {
@ -51,8 +51,6 @@ public abstract class Authenticator {
protected Result () {}
}
/**
* Indicates an authentication failure. The authentication
* attempt has completed.
@ -64,7 +62,7 @@ public abstract class Authenticator {
/**
* Creates a {@code Failure} instance with given response code.
*
* @param responseCode The response code to associate with this
* @param responseCode the response code to associate with this
* {@code Failure} instance
*/
public Failure (int responseCode) {
@ -72,9 +70,9 @@ public abstract class Authenticator {
}
/**
* returns the response code to send to the client
* Returns the response code to send to the client.
*
* @return The response code associated with this {@code Failure} instance
* @return the response code associated with this {@code Failure} instance
*/
public int getResponseCode() {
return responseCode;
@ -83,8 +81,8 @@ public abstract class Authenticator {
/**
* Indicates an authentication has succeeded and the
* authenticated user principal can be acquired by calling
* getPrincipal().
* authenticated user {@linkplain HttpPrincipal principal} can be acquired by calling
* {@link #getPrincipal()}.
*/
public static class Success extends Result {
private HttpPrincipal principal;
@ -92,15 +90,16 @@ public abstract class Authenticator {
/**
* Creates a {@code Success} instance with given {@code Principal}.
*
* @param p The authenticated user you wish to set as Principal
* @param p the authenticated user you wish to set as {@code Principal}
*/
public Success (HttpPrincipal p) {
principal = p;
}
/**
* returns the authenticated user Principal
* Returns the authenticated user {@code Principal}.
*
* @return The {@code Principal} instance associated with the authenticated user
* @return the {@code Principal} instance associated with the authenticated user
*
*/
public HttpPrincipal getPrincipal() {
@ -111,9 +110,9 @@ public abstract class Authenticator {
/**
* Indicates an authentication must be retried. The
* response code to be sent back is as returned from
* getResponseCode(). The Authenticator must also have
* set any necessary response headers in the given HttpExchange
* before returning this Retry object.
* {@link #getResponseCode()}. The {@code Authenticator} must also have
* set any necessary response headers in the given {@link HttpExchange}
* before returning this {@code Retry} object.
*/
public static class Retry extends Result {
@ -122,7 +121,7 @@ public abstract class Authenticator {
/**
* Creates a {@code Retry} instance with given response code.
*
* @param responseCode The response code to associate with this
* @param responseCode the response code to associate with this
* {@code Retry} instance
*/
public Retry (int responseCode) {
@ -130,9 +129,9 @@ public abstract class Authenticator {
}
/**
* returns the response code to send to the client
* Returns the response code to send to the client.
*
* @return The response code associated with this {@code Retry} instance
* @return the response code associated with this {@code Retry} instance
*/
public int getResponseCode() {
return responseCode;
@ -140,23 +139,22 @@ public abstract class Authenticator {
}
/**
* called to authenticate each incoming request. The implementation
* must return a Failure, Success or Retry object as appropriate :-
* <p>
* Failure means the authentication has completed, but has failed
* due to invalid credentials.
* <p>
* Sucess means that the authentication
* has succeeded, and a Principal object representing the user
* can be retrieved by calling Sucess.getPrincipal() .
* <p>
* Retry means that another HTTP exchange is required. Any response
* headers needing to be sent back to the client are set in the
* given HttpExchange. The response code to be returned must be provided
* in the Retry object. Retry may occur multiple times.
* Called to authenticate each incoming request. The implementation
* must return a {@link Failure}, {@link Success} or {@link Retry} object as appropriate:
* <ul>
* <li> {@code Failure} means the authentication has completed, but has
* failed due to invalid credentials.
* <li> {@code Success} means that the authentication has succeeded,
* and a {@code Principal} object representing the user can be retrieved
* by calling {@link Success#getPrincipal()}.
* <li> {@code Retry} means that another HTTP {@linkplain HttpExchange exchange}
* is required. Any response headers needing to be sent back to the client are set
* in the given {@code HttpExchange}. The response code to be returned must be
* provided in the {@code Retry} object. {@code Retry} may occur multiple times.
* <ul/>
*
* @param exch The HttpExchange upon which authenticate is called
* @return The result
* @param exch the {@code HttpExchange} upon which authenticate is called
* @return the result
*/
public abstract Result authenticate (HttpExchange exch);
}

25
src/jdk.httpserver/share/classes/com/sun/net/httpserver/BasicAuthenticator.java
View File

@ -45,11 +45,11 @@ public abstract class BasicAuthenticator extends Authenticator {
private final boolean isUTF8;
/**
* Creates a BasicAuthenticator for the given HTTP realm.
* Creates a {@code BasicAuthenticator} for the given HTTP realm.
* The Basic authentication credentials (username and password) are decoded
* using the platform's {@link Charset#defaultCharset() default character set}.
*
* @param realm The HTTP Basic authentication realm
* @param realm the HTTP Basic authentication realm
* @throws NullPointerException if realm is {@code null}
* @throws IllegalArgumentException if realm is an empty string
*/
@ -58,7 +58,7 @@ public abstract class BasicAuthenticator extends Authenticator {
}
/**
* Creates a BasicAuthenticator for the given HTTP realm and using the
* Creates a {@code BasicAuthenticator} for the given HTTP realm and using the
* given {@link Charset} to decode the Basic authentication credentials
* (username and password).
*
@ -66,8 +66,8 @@ public abstract class BasicAuthenticator extends Authenticator {
* communicated to the client, and therefore more likely to be used also
* by the client.
*
* @param realm The HTTP Basic authentication realm
* @param charset The Charset to decode incoming credentials from the client
* @param realm the HTTP Basic authentication realm
* @param charset the {@code Charset} to decode incoming credentials from the client
* @throws NullPointerException if realm or charset are {@code null}
* @throws IllegalArgumentException if realm is an empty string
*/
@ -81,8 +81,9 @@ public abstract class BasicAuthenticator extends Authenticator {
}
/**
* returns the realm this BasicAuthenticator was created with
* @return the authenticator's realm string.
* Returns the realm this {@code BasicAuthenticator} was created with.
*
* @return the authenticator's realm string
*/
public String getRealm () {
return realm;
@ -130,14 +131,14 @@ public abstract class BasicAuthenticator extends Authenticator {
}
/**
* called for each incoming request to verify the
* Called for each incoming request to verify the
* given name and password in the context of this
* Authenticator's realm. Any caching of credentials
* must be done by the implementation of this method
* authenticator's realm. Any caching of credentials
* must be done by the implementation of this method.
*
* @param username the username from the request
* @param password the password from the request
* @return <code>true</code> if the credentials are valid,
* <code>false</code> otherwise.
* @return {@code true} if the credentials are valid, {@code false} otherwise
*/
public abstract boolean checkCredentials (String username, String password);
}