Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
8253053: Javadoc clean up in Authenticator and BasicAuthenicator
Reviewed-by: dfuchs, rriggs, chegar, michaelm
  • Loading branch information
pconcannon committed Sep 28, 2020
1 parent 840aa2b commit 16b8c39
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 45 deletions.
Expand Up @@ -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 {

Expand All @@ -51,8 +51,6 @@ public abstract static class Result {
protected Result () {}
}



/**
* Indicates an authentication failure. The authentication
* attempt has completed.
Expand All @@ -64,17 +62,17 @@ public static class Failure extends Result {
/**
* 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) {
this.responseCode = responseCode;
}

/**
* 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;
Expand All @@ -83,24 +81,25 @@ public int getResponseCode() {

/**
* 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;

/**
* 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() {
Expand All @@ -111,9 +110,9 @@ public HttpPrincipal getPrincipal() {
/**
* 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 {

Expand All @@ -122,41 +121,40 @@ public static class Retry extends Result {
/**
* 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) {
this.responseCode = responseCode;
}

/**
* 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;
}
}

/**
* 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);
}
Expand Up @@ -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
*/
Expand All @@ -58,16 +58,16 @@ public BasicAuthenticator (String realm) {
}

/**
* 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).
*
* @apiNote {@code UTF-8} is the recommended charset because its usage is
* 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
*/
Expand All @@ -81,8 +81,9 @@ public BasicAuthenticator (String realm, Charset charset) {
}

/**
* 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;
Expand Down Expand Up @@ -130,14 +131,14 @@ private void setAuthHeader(HttpExchange t) {
}

/**
* 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);
}
Expand Down

1 comment on commit 16b8c39

@bridgekeeper
Copy link

@bridgekeeper bridgekeeper bot commented on 16b8c39 Sep 28, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.