Skip to content

Commit 34f68d3

Browse files
lbalmacedalbalmaceda
committed
allow to chain request calls. add AuthAPI javadoc snippets
1 parent bb0a397 commit 34f68d3

12 files changed

Lines changed: 162 additions & 37 deletions

‎README.md‎

Lines changed: 14 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -116,11 +116,11 @@ Creates a new request to create a new user. Up to 10 additional Sign Up fields c
116116

117117
Example:
118118
```java
119-
SignUpRequest request = auth.signUp("user@domain.com", "username", "password123", "Username-Password-Authentication");
120119
Map<String, String> fields = new HashMap<>();
121-
fields.put("location", "Buenos Aires");
122120
fields.put("age", "25");
123-
request.setCustomFields(fields);
121+
fields.put("city", "Buenos Aires");
122+
SignUpRequest request = auth.signUp("user@domain.com", "username", "password123", "Username-Password-Authentication")
123+
.setCustomFields(fields);
124124
try {
125125
request.execute();
126126
} catch (APIException exception) {
@@ -138,12 +138,11 @@ Creates a new request to exchange the `code` previously obtained by calling the
138138

139139
Example:
140140
```java
141-
AuthRequest request = exchangeCode("asdfgh", "https://me.auth0.com/callback");
142-
request.setAudience("https://api.me.auth0.com/users");
143-
request.setScope("openid contacts");
141+
AuthRequest request = exchangeCode("asdfgh", "https://me.auth0.com/callback")
142+
.setAudience("https://api.me.auth0.com/users")
143+
.setScope("openid contacts");
144144
try {
145145
TokenHolder holder = request.execute();
146-
// holder.getAccessToken();
147146
} catch (APIException exception) {
148147
// api error
149148
} catch (Auth0Exception exception) {
@@ -159,12 +158,11 @@ Creates a new request to log in the user with `username` and `password`. The con
159158

160159
Example:
161160
```java
162-
AuthRequest request = login("me@domain.com", "password123");
163-
request.setAudience("https://api.me.auth0.com/users");
164-
request.setScope("openid contacts");
161+
AuthRequest request = login("me@domain.com", "password123")
162+
.setAudience("https://api.me.auth0.com/users")
163+
.setScope("openid contacts");
165164
try {
166165
TokenHolder holder = request.execute();
167-
// holder.getAccessToken();
168166
} catch (APIException exception) {
169167
// api error
170168
} catch (Auth0Exception exception) {
@@ -180,12 +178,11 @@ Creates a new request to log in the user with `username` and `password` using th
180178

181179
Example:
182180
```java
183-
AuthRequest request = login("me@domain.com", "password123", "Username-Password-Authentication");
184-
request.setAudience("https://api.me.auth0.com/users");
185-
request.setScope("openid contacts");
181+
AuthRequest request = login("me@domain.com", "password123", "Username-Password-Authentication")
182+
.setAudience("https://api.me.auth0.com/users")
183+
.setScope("openid contacts");
186184
try {
187185
TokenHolder holder = request.execute();
188-
// holder.getAccessToken();
189186
} catch (APIException exception) {
190187
// api error
191188
} catch (Auth0Exception exception) {
@@ -201,11 +198,10 @@ Creates a new request to get a Token for the given Audience.
201198

202199
Example:
203200
```java
204-
AuthRequest request = requestToken("https://api.me.auth0.com/users");
205-
request.setScope("openid contacts");
201+
AuthRequest request = requestToken("https://api.me.auth0.com/users")
202+
.setScope("openid contacts");
206203
try {
207204
TokenHolder holder = request.execute();
208-
// holder.getAccessToken();
209205
} catch (APIException exception) {
210206
// api error
211207
} catch (Auth0Exception exception) {

‎src/main/java/com/auth0/client/auth/AuthAPI.java‎

Lines changed: 116 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,17 @@ private String createBaseUrl(String domain) {
9999

100100
/**
101101
* Creates a new instance of the {@link AuthorizeUrlBuilder} with the given redirect url.
102+
* i.e.:
103+
* <p>
104+
* <pre>
105+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
106+
* String url = auth.authorizeUrl("https://me.auth0.com/callback")
107+
* .withConnection("facebook")
108+
* .withAudience("https://api.me.auth0.com/users")
109+
* .withScope("openid contacts")
110+
* .withState("my-custom-state")
111+
* .build();
112+
* </pre>
102113
*
103114
* @param redirectUri the redirect_uri value to set, white-listed in the client settings. Must be already URL Encoded.
104115
* @return a new instance of the {@link AuthorizeUrlBuilder} to configure.
@@ -111,6 +122,14 @@ public AuthorizeUrlBuilder authorizeUrl(String redirectUri) {
111122

112123
/**
113124
* Creates a new instance of the {@link LogoutUrlBuilder} with the given return-to url.
125+
* i.e.:
126+
* <p>
127+
* <pre>
128+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
129+
* String url = auth.logoutUrl("https://me.auth0.com/home", true)
130+
* .useFederated(true)
131+
* .withAccessToken("A9CvPwFojaBIA9CvI");
132+
* </pre>
114133
*
115134
* @param returnToUrl the redirect_uri value to set, white-listed in the client settings. Must be already URL Encoded.
116135
* @param setClientId whether the client_id value must be set or not. This affects the white-list that the Auth0's Dashboard uses to validate the returnTo url.
@@ -125,6 +144,16 @@ public LogoutUrlBuilder logoutUrl(String returnToUrl, boolean setClientId) {
125144

126145
/**
127146
* Request the user information related to the access token.
147+
* i.e.:
148+
* <p>
149+
* <pre>
150+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
151+
* try {
152+
* UserInfo result = auth.userInfo("A9CvPwFojaBIA9CvI").execute();
153+
* } catch (Auth0Exception e) {
154+
* //Something happened
155+
* }
156+
* </pre>
128157
*
129158
* @param accessToken a valid access token belonging to an API signed with RS256 algorithm and containing the scope 'openid'.
130159
* @return a Request to execute.
@@ -146,6 +175,16 @@ public Request<UserInfo> userInfo(String accessToken) {
146175
/**
147176
* Request a password reset for the given email and database connection. The response will always be successful even if
148177
* there's no user associated to the given email for that database connection.
178+
* i.e.:
179+
* <p>
180+
* <pre>
181+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
182+
* try {
183+
* auth.resetPassword("me@auth0.com", "db-connection").execute();
184+
* } catch (Auth0Exception e) {
185+
* //Something happened
186+
* }
187+
* </pre>
149188
*
150189
* @param email the email associated to the database user.
151190
* @param connection the database connection where the user was created.
@@ -171,6 +210,21 @@ public Request resetPassword(String email, String connection) {
171210
/**
172211
* Creates a new sign up request with the given credentials and database connection.
173212
* "Requires Username" option must be turned on in the Connection's configuration first.
213+
* i.e.:
214+
* <p>
215+
* <pre>
216+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
217+
* try {
218+
* Map<String, String> fields = new HashMap<String, String>();
219+
* fields.put("age", "25);
220+
* fields.put("city", "Buenos Aires");
221+
* auth.signUp("me@auth0.com", "myself", "topsecret", "db-connection")
222+
* .setCustomFields(fields)
223+
* .execute();
224+
* } catch (Auth0Exception e) {
225+
* //Something happened
226+
* }
227+
* </pre>
174228
*
175229
* @param email the desired user's email.
176230
* @param username the desired user's username.
@@ -188,6 +242,21 @@ public SignUpRequest signUp(String email, String username, String password, Stri
188242

189243
/**
190244
* Creates a new sign up request with the given credentials and database connection.
245+
* i.e.:
246+
* <p>
247+
* <pre>
248+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
249+
* try {
250+
* Map<String, String> fields = new HashMap<String, String>();
251+
* fields.put("age", "25);
252+
* fields.put("city", "Buenos Aires");
253+
* auth.signUp("me@auth0.com", "topsecret", "db-connection")
254+
* .setCustomFields(fields)
255+
* .execute();
256+
* } catch (Auth0Exception e) {
257+
* //Something happened
258+
* }
259+
* </pre>
191260
*
192261
* @param email the desired user's email.
193262
* @param password the desired user's password.
@@ -215,6 +284,18 @@ public SignUpRequest signUp(String email, String password, String connection) {
215284

216285
/**
217286
* Creates a new log in request using the 'Password' grant and the given credentials.
287+
* i.e.:
288+
* <p>
289+
* <pre>
290+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
291+
* try {
292+
* TokenHolder result = auth.login("me@auth0.com", "topsecret")
293+
* .setScope("openid email nickname")
294+
* .execute();
295+
* } catch (Auth0Exception e) {
296+
* //Something happened
297+
* }
298+
* </pre>
218299
*
219300
* @param emailOrUsername the identity of the user.
220301
* @param password the password of the user.
@@ -233,7 +314,7 @@ public AuthRequest login(String emailOrUsername, String password) {
233314
TokenRequest request = new TokenRequest(client, url);
234315
request.addParameter(KEY_CLIENT_ID, clientId);
235316
request.addParameter(KEY_CLIENT_SECRET, clientSecret);
236-
request.addParameter(KEY_GRANT_TYPE, KEY_PASSWORD);
317+
request.addParameter(KEY_GRANT_TYPE, "password");
237318
request.addParameter(KEY_USERNAME, emailOrUsername);
238319
request.addParameter(KEY_PASSWORD, password);
239320
return request;
@@ -242,6 +323,17 @@ public AuthRequest login(String emailOrUsername, String password) {
242323
/**
243324
* Creates a new log in request using the 'Password Realm' grant and the given credentials.
244325
* Default used realm and audience are defined in the "API Authorization Settings" in the account's advanced settings in the Auth0 Dashboard.
326+
* <p>
327+
* <pre>
328+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
329+
* try {
330+
* TokenHolder result = auth.login("me@auth0.com", "topsecret", "my-realm")
331+
* .setAudience("https://myapi.me.auth0.com/users")
332+
* .execute();
333+
* } catch (Auth0Exception e) {
334+
* //Something happened
335+
* }
336+
* </pre>
245337
*
246338
* @param emailOrUsername the identity of the user.
247339
* @param password the password of the user.
@@ -270,7 +362,18 @@ public AuthRequest login(String emailOrUsername, String password, String realm)
270362

271363
/**
272364
* Creates a new request to get a Token for the given audience using the 'Client Credentials' grant.
273-
* Default used realm and audience are defined in the "API Authorization Settings" in the account's advanced settings in the Auth0 Dashboard.
365+
* Default used realm is defined in the "API Authorization Settings" in the account's advanced settings in the Auth0 Dashboard.
366+
* <p>
367+
* <pre>
368+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
369+
* try {
370+
* TokenHolder result = auth.requestToken("https://myapi.me.auth0.com/users")
371+
* .setRealm("my-realm")
372+
* .execute();
373+
* } catch (Auth0Exception e) {
374+
* //Something happened
375+
* }
376+
* </pre>
274377
*
275378
* @param audience the audience of the API to request access to.
276379
* @return a Request to configure and execute.
@@ -294,6 +397,17 @@ public AuthRequest requestToken(String audience) {
294397

295398
/**
296399
* Creates a new request to exchange the code obtained in the /authorize call using the 'Authorization Code' grant.
400+
* <p>
401+
* <pre>
402+
* AuthAPI auth = new AuthAPI("me.auth0.com", "B3c6RYhk1v9SbIJcRIOwu62gIUGsnze", "2679NfkaBn62e6w5E8zNEzjr-yWfkaBne");
403+
* try {
404+
* TokenHolder result = auth.exchangeCode("SnWoFLMzApDskr", "https://me.auth0.com/callback")
405+
* .setScope("openid name nickname")
406+
* .execute();
407+
* } catch (Auth0Exception e) {
408+
* //Something happened
409+
* }
410+
* </pre>
297411
*
298412
* @param code the authorization code received from the /authorize call.
299413
* @param redirectUri the redirect uri sent on the /authorize call.

‎src/main/java/com/auth0/client/auth/AuthorizeUrlBuilder.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
/**
1212
* Class that provides the methods to generate a valid Auth0 Authorize Url. It's based on the https://auth0.com/docs/api/authentication#social docs.
1313
*/
14+
@SuppressWarnings("WeakerAccess")
1415
public class AuthorizeUrlBuilder {
1516

1617
private final HttpUrl.Builder builder;

‎src/main/java/com/auth0/client/auth/LogoutUrlBuilder.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
/**
1212
* Class that provides the methods to generate a valid Auth0 Logout Url. It's based on the https://auth0.com/docs/api/authentication#logout docs.
1313
*/
14+
@SuppressWarnings("WeakerAccess")
1415
public class LogoutUrlBuilder {
1516

1617
private final HttpUrl.Builder builder;

‎src/main/java/com/auth0/net/AuthRequest.java‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,20 +11,23 @@ public interface AuthRequest extends Request<TokenHolder> {
1111
* Setter for the realm value to request
1212
*
1313
* @param realm the realm to request
14+
* @return this request instance.
1415
*/
15-
void setRealm(String realm);
16+
AuthRequest setRealm(String realm);
1617

1718
/**
1819
* Setter for the audience value to request
1920
*
2021
* @param audience the audience to request
22+
* @return this request instance.
2123
*/
22-
void setAudience(String audience);
24+
AuthRequest setAudience(String audience);
2325

2426
/**
2527
* Setter for the scope value to request
2628
*
2729
* @param scope the scope to request
30+
* @return this request instance.
2831
*/
29-
void setScope(String scope);
32+
AuthRequest setScope(String scope);
3033
}

‎src/main/java/com/auth0/net/BaseRequest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ public abstract class BaseRequest<T> implements Request<T> {
1010

1111
private final OkHttpClient client;
1212

13-
public BaseRequest(OkHttpClient client) {
13+
BaseRequest(OkHttpClient client) {
1414
this.client = client;
1515
}
1616

‎src/main/java/com/auth0/net/CustomRequest.java‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
package com.auth0.net;
22

3-
import com.auth0.exception.Auth0Exception;
43
import com.auth0.exception.APIException;
4+
import com.auth0.exception.Auth0Exception;
55
import com.fasterxml.jackson.core.JsonProcessingException;
66
import com.fasterxml.jackson.core.type.TypeReference;
77
import com.fasterxml.jackson.databind.ObjectMapper;
@@ -13,6 +13,7 @@
1313
import java.util.HashMap;
1414
import java.util.Map;
1515

16+
@SuppressWarnings("WeakerAccess")
1617
public class CustomRequest<T> extends BaseRequest<T> implements CustomizableRequest<T> {
1718
private static final String CONTENT_TYPE_APPLICATION_JSON = "application/json";
1819

@@ -66,18 +67,21 @@ protected T parseResponse(Response response) throws Auth0Exception {
6667
}
6768

6869
@Override
69-
public void addHeader(String name, String value) {
70+
public CustomRequest<T> addHeader(String name, String value) {
7071
headers.put(name, value);
72+
return this;
7173
}
7274

7375
@Override
74-
public void addParameter(String name, Object value) {
76+
public CustomRequest<T> addParameter(String name, Object value) {
7577
parameters.put(name, value);
78+
return this;
7679
}
7780

7881
@Override
79-
public void setBody(Object value) {
82+
public CustomRequest<T> setBody(Object value) {
8083
body = value;
84+
return this;
8185
}
8286

8387
protected RequestBody createBody() throws Auth0Exception {

‎src/main/java/com/auth0/net/CustomizableRequest.java‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
interface CustomizableRequest<T> extends Request<T> {
44

5-
void addHeader(String name, String value);
5+
CustomizableRequest<T> addHeader(String name, String value);
66

7-
void addParameter(String name, Object value);
7+
CustomizableRequest<T> addParameter(String name, Object value);
88

9-
void setBody(Object body);
9+
CustomizableRequest<T> setBody(Object body);
1010
}

‎src/main/java/com/auth0/net/EmptyBodyRequest.java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@ protected RequestBody createBody() throws Auth0Exception {
1717
}
1818

1919
@Override
20-
public void addParameter(String name, Object value) {
20+
public EmptyBodyRequest<T> addParameter(String name, Object value) {
2121
//do nothing
22+
return this;
2223
}
2324
}

‎src/main/java/com/auth0/net/SignUpRequest.java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ public interface SignUpRequest extends Request<Void> {
1111
* Setter for the additional fields to set when creating a user.
1212
*
1313
* @param customFields the list of custom fields.
14+
* @return this request instance.
1415
*/
15-
void setCustomFields(Map<String, String> customFields);
16+
SignUpRequest setCustomFields(Map<String, String> customFields);
1617
}

0 commit comments

Comments
 (0)