Rename Token to Credentials

hzalaz · hzalaz · commit 3625468de19d · 2016-03-15T20:36:52.000-03:00
diff --git a/lib/src/main/java/com/auth0/authentication/AuthenticationAPIClient.java b/lib/src/main/java/com/auth0/authentication/AuthenticationAPIClient.java
@@ -25,9 +25,9 @@
 package com.auth0.authentication;
 
 import com.auth0.Auth0;
+import com.auth0.authentication.result.Credentials;
 import com.auth0.authentication.result.DatabaseUser;
 import com.auth0.authentication.result.Delegation;
-import com.auth0.authentication.result.Token;
 import com.auth0.authentication.result.UserProfile;
 import com.auth0.internal.RequestFactory;
 import com.auth0.request.ParameterizableRequest;
@@ -69,7 +69,6 @@ public class AuthenticationAPIClient {
     private static final String OAUTH_PATH = "oauth";
     private static final String RESOURCE_OWNER_PATH = "ro";
     private static final String TOKEN_INFO_PATH = "tokeninfo";
-    private static final String ID_TOKEN = "id_token";
 
     private final Auth0 auth0;
     private final OkHttpClient client;
@@ -137,13 +136,13 @@ public void setDefaultDbConnection(String defaultDbConnection) {
     }
 
     /**
-     * Log in a user with email/username and password using a DB connection and fetch it's profile from Auth0
+     * Log in a user with email/username and password using a DB connection
      *
      * @param usernameOrEmail of the user depending of the type of DB connection
      * @param password        of the user
-     * @return a request to configure and start that will yield {@link Token} and {@link UserProfile}
+     * @return a request to configure and start that will yield {@link Credentials}
      */
-    public ParameterizableRequest<Token> login(String usernameOrEmail, String password) {
+    public ParameterizableRequest<Credentials> login(String usernameOrEmail, String password) {
         Map<String, Object> requestParameters = ParameterBuilder.newAuthenticationBuilder()
                 .set(USERNAME_KEY, usernameOrEmail)
                 .set(PASSWORD_KEY, password)
@@ -157,9 +156,9 @@ public ParameterizableRequest<Token> login(String usernameOrEmail, String passwo
      *
      * @param token      obtained from the IdP
      * @param connection that will be used to authenticate the user, e.g. 'facebook'
-     * @return a request to configure and start that will yield {@link Token} and {@link UserProfile}
+     * @return a request to configure and start that will yield {@link Credentials}
      */
-    public ParameterizableRequest<Token> loginWithOAuthAccessToken(String token, String connection) {
+    public ParameterizableRequest<Credentials> loginWithOAuthAccessToken(String token, String connection) {
         HttpUrl url = HttpUrl.parse(auth0.getDomainUrl()).newBuilder()
                 .addPathSegment(OAUTH_PATH)
                 .addPathSegment(ACCESS_TOKEN_PATH)
@@ -171,7 +170,7 @@ public ParameterizableRequest<Token> loginWithOAuthAccessToken(String token, Str
                 .setAccessToken(token)
                 .asDictionary();
 
-        ParameterizableRequest<Token> credentialsRequest = factory.POST(url, client, mapper, Token.class);
+        ParameterizableRequest<Credentials> credentialsRequest = factory.POST(url, client, mapper, Credentials.class);
         credentialsRequest.getParameterBuilder().addAll(parameters);
         return credentialsRequest;
     }
@@ -181,9 +180,9 @@ public ParameterizableRequest<Token> loginWithOAuthAccessToken(String token, Str
      *
      * @param phoneNumber      where the user received the verification code
      * @param verificationCode sent by Auth0 via SMS
-     * @return a request to configure and start that will yield {@link Token} and {@link UserProfile}
+     * @return a request to configure and start that will yield {@link Credentials}
      */
-    public ParameterizableRequest<Token> loginWithPhoneNumber(String phoneNumber, String verificationCode) {
+    public ParameterizableRequest<Credentials> loginWithPhoneNumber(String phoneNumber, String verificationCode) {
         Map<String, Object> parameters = ParameterBuilder.newAuthenticationBuilder()
                 .set(USERNAME_KEY, phoneNumber)
                 .set(PASSWORD_KEY, verificationCode)
@@ -199,9 +198,9 @@ public ParameterizableRequest<Token> loginWithPhoneNumber(String phoneNumber, St
      *
      * @param email            where the user received the verification code
      * @param verificationCode sent by Auth0 via Email
-     * @return a request to configure and start that will yield {@link Token} and {@link UserProfile}
+     * @return a request to configure and start that will yield {@link Credentials}
      */
-    public ParameterizableRequest<Token> loginWithEmail(String email, String verificationCode) {
+    public ParameterizableRequest<Credentials> loginWithEmail(String email, String verificationCode) {
         Map<String, Object> parameters = ParameterBuilder.newAuthenticationBuilder()
                 .set(USERNAME_KEY, email)
                 .set(PASSWORD_KEY, verificationCode)
@@ -261,40 +260,40 @@ public ParameterizableRequest<DatabaseUser> createUser(String email, String pass
 
     /**
      * Creates a user in a DB connection using <a href="https://auth0.com/docs/auth-api#!#post--dbconnections-signup">'/dbconnections/signup' endpoint</a>
-     * and then logs in and fetches it's user profile
+     * and then logs in
      *
      * @param email    of the user and must be non null
      * @param password of the user and must be non null
      * @param username of the user and must be non null
-     * @return a request to configure and start that will yield {@link Token} and {@link UserProfile}
+     * @return a request to configure and start that will yield {@link Credentials}
      */
     public SignUpRequest signUp(String email, String password, String username) {
         final ParameterizableRequest<DatabaseUser> createUserRequest = createUser(email, password, username);
-        final ParameterizableRequest<Token> authenticationRequest = login(email, password);
+        final ParameterizableRequest<Credentials> authenticationRequest = login(email, password);
         return new SignUpRequest(createUserRequest, authenticationRequest);
     }
 
     /**
      * Creates a user in a DB connection using <a href="https://auth0.com/docs/auth-api#!#post--dbconnections-signup">'/dbconnections/signup' endpoint</a>
-     * and then logs in and fetches it's user profile
+     * and then logs in
      *
      * @param email    of the user and must be non null
      * @param password of the user and must be non null
-     * @return a request to configure and start that will yield {@link Token} and {@link UserProfile}
+     * @return a request to configure and start that will yield {@link Credentials}
      */
     public SignUpRequest signUp(String email, String password) {
         ParameterizableRequest<DatabaseUser> createUserRequest = createUser(email, password);
-        final ParameterizableRequest<Token> authenticationRequest = login(email, password);
+        final ParameterizableRequest<Credentials> authenticationRequest = login(email, password);
         return new SignUpRequest(createUserRequest, authenticationRequest);
     }
 
     /**
-     * Perform a change password request using <a href="https://auth0.com/docs/auth-api#!#post--dbconnections-change_password">'/dbconnections/change_password'</a>
+     * Request a change password using <a href="https://auth0.com/docs/auth-api#!#post--dbconnections-change_password">'/dbconnections/change_password'</a>
      *
-     * @param email of the user that changes the password. It's also where the confirmation email will be sent
+     * @param email of the user that changes the password. It's also where the email will be sent with the link to perform the change password.
      * @return a request to configure and start
      */
-    public ChangePasswordRequest changePassword(String email) {
+    public ChangePasswordRequest requestChangePassword(String email) {
         HttpUrl url = HttpUrl.parse(auth0.getDomainUrl()).newBuilder()
                 .addPathSegment(DB_CONNECTIONS_PATH)
                 .addPathSegment(CHANGE_PASSWORD_PATH)
@@ -466,18 +465,24 @@ public ParameterizableRequest<Void> passwordless() {
         return request;
     }
 
-    public AuthenticationRequest getProfileAfter(ParameterizableRequest<Token> loginRequest) {
+    /**
+     * Fetch the user's profile after it's authenticated by a login request.
+     * If the login request fails, the returned request will fail
+     * @param loginRequest that will authenticate a user with Auth0 and return a {@see Credentials}
+     * @return a {@see AuthenticationRequest} that first logins and the fetches the profile
+     */
+    public AuthenticationRequest getProfileAfter(ParameterizableRequest<Credentials> loginRequest) {
         final ParameterizableRequest<UserProfile> profileRequest = profileRequest();
         return new AuthenticationRequest(loginRequest, profileRequest);
     }
 
-    protected ParameterizableRequest<Token> loginWithResourceOwner(Map<String, Object> parameters) {
+    protected ParameterizableRequest<Credentials> loginWithResourceOwner(Map<String, Object> parameters) {
         HttpUrl url = HttpUrl.parse(auth0.getDomainUrl()).newBuilder()
                 .addPathSegment(OAUTH_PATH)
                 .addPathSegment(RESOURCE_OWNER_PATH)
                 .build();
 
-        ParameterizableRequest<Token> request = factory.POST(url, client, mapper, Token.class);
+        ParameterizableRequest<Credentials> request = factory.POST(url, client, mapper, Credentials.class);
         request.getParameterBuilder()
                 .setClientId(getClientId())
                 .setConnection(defaultDbConnection)
diff --git a/lib/src/main/java/com/auth0/authentication/AuthenticationRequest.java b/lib/src/main/java/com/auth0/authentication/AuthenticationRequest.java
@@ -25,10 +25,10 @@
 package com.auth0.authentication;
 
 import com.auth0.Auth0Exception;
+import com.auth0.authentication.result.Credentials;
 import com.auth0.request.ParameterizableRequest;
 import com.auth0.request.Request;
 import com.auth0.callback.BaseCallback;
-import com.auth0.authentication.result.Token;
 import com.auth0.authentication.result.UserProfile;
 import com.auth0.authentication.result.Authentication;
 
@@ -41,10 +41,10 @@ public class AuthenticationRequest implements Request<Authentication> {
 
     private static final String ID_TOKEN_KEY = "id_token";
 
-    private final ParameterizableRequest<Token> credentialsRequest;
+    private final ParameterizableRequest<Credentials> credentialsRequest;
     private final ParameterizableRequest<UserProfile> tokenInfoRequest;
 
-    AuthenticationRequest(ParameterizableRequest<Token> credentialsRequest, ParameterizableRequest<UserProfile> tokenInfoRequest) {
+    AuthenticationRequest(ParameterizableRequest<Credentials> credentialsRequest, ParameterizableRequest<UserProfile> tokenInfoRequest) {
         this.credentialsRequest = credentialsRequest;
         this.tokenInfoRequest = tokenInfoRequest;
     }
@@ -89,17 +89,17 @@ public AuthenticationRequest setConnection(String connection) {
      */
     @Override
     public void start(final BaseCallback<Authentication> callback) {
-        credentialsRequest.start(new BaseCallback<Token>() {
+        credentialsRequest.start(new BaseCallback<Credentials>() {
             @Override
-            public void onSuccess(final Token token) {
+            public void onSuccess(final Credentials credentials) {
                 tokenInfoRequest
                         .getParameterBuilder()
-                        .set(ID_TOKEN_KEY, token.getIdToken());
+                        .set(ID_TOKEN_KEY, credentials.getIdToken());
                 tokenInfoRequest
                         .start(new BaseCallback<UserProfile>() {
                             @Override
                             public void onSuccess(UserProfile profile) {
-                                callback.onSuccess(new Authentication(profile, token));
+                                callback.onSuccess(new Authentication(profile, credentials));
                             }
 
                             @Override
@@ -124,10 +124,10 @@ public void onFailure(Auth0Exception error) {
      */
     @Override
     public Authentication execute() throws Auth0Exception {
-        Token token = credentialsRequest.execute();
-        tokenInfoRequest.getParameterBuilder().set(ID_TOKEN_KEY, token.getIdToken());
+        Credentials credentials = credentialsRequest.execute();
+        tokenInfoRequest.getParameterBuilder().set(ID_TOKEN_KEY, credentials.getIdToken());
         UserProfile profile = tokenInfoRequest
                 .execute();
-        return new Authentication(profile, token);
+        return new Authentication(profile, credentials);
     }
 }
diff --git a/lib/src/main/java/com/auth0/authentication/SignUpRequest.java b/lib/src/main/java/com/auth0/authentication/SignUpRequest.java
@@ -25,24 +25,23 @@
 package com.auth0.authentication;
 
 import com.auth0.Auth0Exception;
-import com.auth0.authentication.result.Token;
+import com.auth0.authentication.result.Credentials;
 import com.auth0.request.ParameterizableRequest;
 import com.auth0.request.Request;
 import com.auth0.callback.BaseCallback;
 import com.auth0.authentication.result.DatabaseUser;
-import com.auth0.authentication.result.Authentication;
 
 import java.util.Map;
 
 /**
  * Represent a request to create a user + log in
  */
-public class SignUpRequest implements Request<Token> {
+public class SignUpRequest implements Request<Credentials> {
 
     private final ParameterizableRequest<DatabaseUser> signUpRequest;
-    private final ParameterizableRequest<Token> authenticationRequest;
+    private final ParameterizableRequest<Credentials> authenticationRequest;
 
-    SignUpRequest(ParameterizableRequest<DatabaseUser> signUpRequest, ParameterizableRequest<Token> authenticationRequest) {
+    SignUpRequest(ParameterizableRequest<DatabaseUser> signUpRequest, ParameterizableRequest<Credentials> authenticationRequest) {
         this.signUpRequest = signUpRequest;
         this.authenticationRequest = authenticationRequest;
     }
@@ -98,7 +97,7 @@ public SignUpRequest setConnection(String connection) {
      * @param callback called on either success or failure.
      */
     @Override
-    public void start(final BaseCallback<Token> callback) {
+    public void start(final BaseCallback<Credentials> callback) {
         signUpRequest.start(new BaseCallback<DatabaseUser>() {
             @Override
             public void onSuccess(final DatabaseUser user) {
@@ -119,7 +118,7 @@ public void onFailure(Auth0Exception error) {
      * @throws Auth0Exception on failure
      */
     @Override
-    public Token execute() throws Auth0Exception {
+    public Credentials execute() throws Auth0Exception {
         signUpRequest.execute();
         return authenticationRequest.execute();
     }
diff --git a/lib/src/main/java/com/auth0/authentication/result/Authentication.java b/lib/src/main/java/com/auth0/authentication/result/Authentication.java
@@ -29,25 +29,26 @@
 
 /**
  * The result of a successful authentication against Auth0
- * Contains the logged in user's {@link Token} and {@link UserProfile}
+ * Contains the logged in user's {@link Credentials} and {@link UserProfile}.
+ * @see com.auth0.authentication.AuthenticationAPIClient#getProfileAfter(com.auth0.request.ParameterizableRequest)
  */
 public class Authentication {
 
     private final UserProfile profile;
-    private final Token token;
+    private final Credentials credentials;
 
-    public Authentication(UserProfile profile, Token token) {
+    public Authentication(UserProfile profile, Credentials credentials) {
         checkArgument(profile != null, "profile must be non-null");
-        checkArgument(token != null, "token must be non-null");
+        checkArgument(credentials != null, "credentials must be non-null");
         this.profile = profile;
-        this.token = token;
+        this.credentials = credentials;
     }
 
     public UserProfile getProfile() {
         return profile;
     }
 
-    public Token getToken() {
-        return token;
+    public Credentials getCredentials() {
+        return credentials;
     }
 }
diff --git a/lib/src/main/java/com/auth0/authentication/result/Credentials.java b/lib/src/main/java/com/auth0/authentication/result/Credentials.java
@@ -28,31 +28,34 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
- * Class that holds a user's token information.
+ * Holds the user's credentials returned by Auth0.
+ * <ul>
+ *     <li><i>idToken</i>: Identity Token with user information</li>
+ *     <li><i>accessToken</i>: Access Token for Auth0 API</li>
+ *     <li><i>refreshToken</i>: Refresh Token that can be used to request new tokens without signing in again</li>
+ * </ul>
  */
 @JsonIgnoreProperties(ignoreUnknown = true)
-public class Token {
+public class Credentials {
 
     protected String idToken;
     protected String accessToken;
     protected String type;
     protected String refreshToken;
 
-    protected Token(Token token) {
-        idToken = token.idToken;
-        accessToken = token.accessToken;
-        type = token.type;
-        refreshToken = token.refreshToken;
+    protected Credentials(Credentials credentials) {
+        idToken = credentials.idToken;
+        accessToken = credentials.accessToken;
+        type = credentials.type;
+        refreshToken = credentials.refreshToken;
     }
 
-    protected Token() {
+    protected Credentials() { }
 
-    }
-
-    public Token(@JsonProperty(value = "id_token", required = true) String idToken,
-                 @JsonProperty(value = "access_token") String accessToken,
-                 @JsonProperty(value = "token_type") String type,
-                 @JsonProperty(value = "refresh_token") String refreshToken) {
+    public Credentials(@JsonProperty(value = "id_token", required = true) String idToken,
+                       @JsonProperty(value = "access_token") String accessToken,
+                       @JsonProperty(value = "token_type") String type,
+                       @JsonProperty(value = "refresh_token") String refreshToken) {
         this.idToken = idToken;
         this.accessToken = accessToken;
         this.type = type;
diff --git a/lib/src/main/java/com/auth0/authentication/result/DatabaseUser.java b/lib/src/main/java/com/auth0/authentication/result/DatabaseUser.java
@@ -28,7 +28,10 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
- * Value holder for Database Sign Up operation
+ * Auth0 user created in a Database connection.
+ *
+ * @see com.auth0.authentication.AuthenticationAPIClient#signUp(String, String)
+ * @see com.auth0.authentication.AuthenticationAPIClient#signUp(String, String, String)
  */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class DatabaseUser {
diff --git a/lib/src/main/java/com/auth0/authentication/result/Delegation.java b/lib/src/main/java/com/auth0/authentication/result/Delegation.java
@@ -31,8 +31,7 @@
 import static com.auth0.util.CheckHelper.checkArgument;
 
 /**
- * The result of a successful delegation to an Auth0 app.
- * Contains a new Auth0 'id_token' to be used on the 'target' app
+ * The result of a successful delegation to an Auth0 application that contains a new Auth0 'id_token'
  * See <a href="https://auth0.com/docs/auth-api#!#post--delegation">delegation</a> docs
  */
 @JsonIgnoreProperties(ignoreUnknown = true)
@@ -54,7 +53,7 @@ public Delegation(@JsonProperty(value = "id_token") String idToken,
     }
 
     /**
-     * Id token
+     * Identity Token
      * @return the 'id_token' value
      */
     public String getIdToken() {
diff --git a/lib/src/main/java/com/auth0/authentication/result/UserProfile.java b/lib/src/main/java/com/auth0/authentication/result/UserProfile.java
diff --git a/lib/src/test/java/com/auth0/authentication/AuthenticationAPIClientTest.java b/lib/src/test/java/com/auth0/authentication/AuthenticationAPIClientTest.java
