Skip to content

Commit 16b8c39

Browse files
committed
8253053: Javadoc clean up in Authenticator and BasicAuthenicator
Reviewed-by: dfuchs, rriggs, chegar, michaelm
1 parent 840aa2b commit 16b8c39

File tree

2 files changed

+44
-45
lines changed

2 files changed

+44
-45
lines changed

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

Lines changed: 31 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ public abstract class Authenticator {
4141
protected Authenticator () { }
4242

4343
/**
44-
* Base class for return type from authenticate() method
44+
* Base class for return type from {@link #authenticate(HttpExchange)} method.
4545
*/
4646
public abstract static class Result {
4747

@@ -51,8 +51,6 @@ public abstract static class Result {
5151
protected Result () {}
5252
}
5353

54-
55-
5654
/**
5755
* Indicates an authentication failure. The authentication
5856
* attempt has completed.
@@ -64,17 +62,17 @@ public static class Failure extends Result {
6462
/**
6563
* Creates a {@code Failure} instance with given response code.
6664
*
67-
* @param responseCode The response code to associate with this
65+
* @param responseCode the response code to associate with this
6866
* {@code Failure} instance
6967
*/
7068
public Failure (int responseCode) {
7169
this.responseCode = responseCode;
7270
}
7371

7472
/**
75-
* returns the response code to send to the client
73+
* Returns the response code to send to the client.
7674
*
77-
* @return The response code associated with this {@code Failure} instance
75+
* @return the response code associated with this {@code Failure} instance
7876
*/
7977
public int getResponseCode() {
8078
return responseCode;
@@ -83,24 +81,25 @@ public int getResponseCode() {
8381

8482
/**
8583
* Indicates an authentication has succeeded and the
86-
* authenticated user principal can be acquired by calling
87-
* getPrincipal().
84+
* authenticated user {@linkplain HttpPrincipal principal} can be acquired by calling
85+
* {@link #getPrincipal()}.
8886
*/
8987
public static class Success extends Result {
9088
private HttpPrincipal principal;
9189

9290
/**
9391
* Creates a {@code Success} instance with given {@code Principal}.
9492
*
95-
* @param p The authenticated user you wish to set as Principal
93+
* @param p the authenticated user you wish to set as {@code Principal}
9694
*/
9795
public Success (HttpPrincipal p) {
9896
principal = p;
9997
}
98+
10099
/**
101-
* returns the authenticated user Principal
100+
* Returns the authenticated user {@code Principal}.
102101
*
103-
* @return The {@code Principal} instance associated with the authenticated user
102+
* @return the {@code Principal} instance associated with the authenticated user
104103
*
105104
*/
106105
public HttpPrincipal getPrincipal() {
@@ -111,9 +110,9 @@ public HttpPrincipal getPrincipal() {
111110
/**
112111
* Indicates an authentication must be retried. The
113112
* response code to be sent back is as returned from
114-
* getResponseCode(). The Authenticator must also have
115-
* set any necessary response headers in the given HttpExchange
116-
* before returning this Retry object.
113+
* {@link #getResponseCode()}. The {@code Authenticator} must also have
114+
* set any necessary response headers in the given {@link HttpExchange}
115+
* before returning this {@code Retry} object.
117116
*/
118117
public static class Retry extends Result {
119118

@@ -122,41 +121,40 @@ public static class Retry extends Result {
122121
/**
123122
* Creates a {@code Retry} instance with given response code.
124123
*
125-
* @param responseCode The response code to associate with this
124+
* @param responseCode the response code to associate with this
126125
* {@code Retry} instance
127126
*/
128127
public Retry (int responseCode) {
129128
this.responseCode = responseCode;
130129
}
131130

132131
/**
133-
* returns the response code to send to the client
132+
* Returns the response code to send to the client.
134133
*
135-
* @return The response code associated with this {@code Retry} instance
134+
* @return the response code associated with this {@code Retry} instance
136135
*/
137136
public int getResponseCode() {
138137
return responseCode;
139138
}
140139
}
141140

142141
/**
143-
* called to authenticate each incoming request. The implementation
144-
* must return a Failure, Success or Retry object as appropriate :-
145-
* <p>
146-
* Failure means the authentication has completed, but has failed
147-
* due to invalid credentials.
148-
* <p>
149-
* Sucess means that the authentication
150-
* has succeeded, and a Principal object representing the user
151-
* can be retrieved by calling Sucess.getPrincipal() .
152-
* <p>
153-
* Retry means that another HTTP exchange is required. Any response
154-
* headers needing to be sent back to the client are set in the
155-
* given HttpExchange. The response code to be returned must be provided
156-
* in the Retry object. Retry may occur multiple times.
142+
* Called to authenticate each incoming request. The implementation
143+
* must return a {@link Failure}, {@link Success} or {@link Retry} object as appropriate:
144+
* <ul>
145+
* <li> {@code Failure} means the authentication has completed, but has
146+
* failed due to invalid credentials.
147+
* <li> {@code Success} means that the authentication has succeeded,
148+
* and a {@code Principal} object representing the user can be retrieved
149+
* by calling {@link Success#getPrincipal()}.
150+
* <li> {@code Retry} means that another HTTP {@linkplain HttpExchange exchange}
151+
* is required. Any response headers needing to be sent back to the client are set
152+
* in the given {@code HttpExchange}. The response code to be returned must be
153+
* provided in the {@code Retry} object. {@code Retry} may occur multiple times.
154+
* <ul/>
157155
*
158-
* @param exch The HttpExchange upon which authenticate is called
159-
* @return The result
156+
* @param exch the {@code HttpExchange} upon which authenticate is called
157+
* @return the result
160158
*/
161159
public abstract Result authenticate (HttpExchange exch);
162160
}

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

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,11 @@ public abstract class BasicAuthenticator extends Authenticator {
4545
private final boolean isUTF8;
4646

4747
/**
48-
* Creates a BasicAuthenticator for the given HTTP realm.
48+
* Creates a {@code BasicAuthenticator} for the given HTTP realm.
4949
* The Basic authentication credentials (username and password) are decoded
5050
* using the platform's {@link Charset#defaultCharset() default character set}.
5151
*
52-
* @param realm The HTTP Basic authentication realm
52+
* @param realm the HTTP Basic authentication realm
5353
* @throws NullPointerException if realm is {@code null}
5454
* @throws IllegalArgumentException if realm is an empty string
5555
*/
@@ -58,16 +58,16 @@ public BasicAuthenticator (String realm) {
5858
}
5959

6060
/**
61-
* Creates a BasicAuthenticator for the given HTTP realm and using the
61+
* Creates a {@code BasicAuthenticator} for the given HTTP realm and using the
6262
* given {@link Charset} to decode the Basic authentication credentials
6363
* (username and password).
6464
*
6565
* @apiNote {@code UTF-8} is the recommended charset because its usage is
6666
* communicated to the client, and therefore more likely to be used also
6767
* by the client.
6868
*
69-
* @param realm The HTTP Basic authentication realm
70-
* @param charset The Charset to decode incoming credentials from the client
69+
* @param realm the HTTP Basic authentication realm
70+
* @param charset the {@code Charset} to decode incoming credentials from the client
7171
* @throws NullPointerException if realm or charset are {@code null}
7272
* @throws IllegalArgumentException if realm is an empty string
7373
*/
@@ -81,8 +81,9 @@ public BasicAuthenticator (String realm, Charset charset) {
8181
}
8282

8383
/**
84-
* returns the realm this BasicAuthenticator was created with
85-
* @return the authenticator's realm string.
84+
* Returns the realm this {@code BasicAuthenticator} was created with.
85+
*
86+
* @return the authenticator's realm string
8687
*/
8788
public String getRealm () {
8889
return realm;
@@ -130,14 +131,14 @@ private void setAuthHeader(HttpExchange t) {
130131
}
131132

132133
/**
133-
* called for each incoming request to verify the
134+
* Called for each incoming request to verify the
134135
* given name and password in the context of this
135-
* Authenticator's realm. Any caching of credentials
136-
* must be done by the implementation of this method
136+
* authenticator's realm. Any caching of credentials
137+
* must be done by the implementation of this method.
138+
*
137139
* @param username the username from the request
138140
* @param password the password from the request
139-
* @return <code>true</code> if the credentials are valid,
140-
* <code>false</code> otherwise.
141+
* @return {@code true} if the credentials are valid, {@code false} otherwise
141142
*/
142143
public abstract boolean checkCredentials (String username, String password);
143144
}

0 commit comments

Comments
 (0)