From f612c105142c9dbf46a08071ef7b43cac5c45666 Mon Sep 17 00:00:00 2001
From: Nitzan Jaitman <nitzan@cloudinary.com>
Date: Tue, 10 Sep 2019 13:27:14 +0300
Subject: [PATCH] Rename Account API method names, add convenience overloads.

---
 .../com/cloudinary/provisioning/Account.java  | 227 +++++++++++++++++-
 .../test/AbstractAccountApiTest.java          |  24 +-
 2 files changed, 228 insertions(+), 23 deletions(-)

diff --git a/cloudinary-core/src/main/java/com/cloudinary/provisioning/Account.java b/cloudinary-core/src/main/java/com/cloudinary/provisioning/Account.java
index cdab08b8..76b56fd0 100644
--- a/cloudinary-core/src/main/java/com/cloudinary/provisioning/Account.java
+++ b/cloudinary-core/src/main/java/com/cloudinary/provisioning/Account.java
@@ -101,6 +101,16 @@ public String toString() {
     }
 
     // Sub accounts
+    /**
+     * Get details of a specific sub account
+     *
+     * @param subAccountId The id of the sub account
+     * @return the sub account details.
+     * @throws Exception If the request fails
+     */
+    public ApiResponse subAccount(String subAccountId) throws Exception {
+        return subAccount(subAccountId, Collections.<String, Object>emptyMap());
+    }
 
     /**
      * Get details of a specific sub account
@@ -110,11 +120,24 @@ public String toString() {
      * @return the sub account details.
      * @throws Exception If the request fails
      */
-    public ApiResponse getSubAccount(String subAccountId, Map<String, Object> options) throws Exception {
+    public ApiResponse subAccount(String subAccountId, Map<String, Object> options) throws Exception {
         List<String> uri = Arrays.asList(PROVISIONING, ACCOUNTS, accountId, "sub_accounts", subAccountId);
         return callAccountApi(Api.HttpMethod.GET, uri, Collections.<String, Object>emptyMap(), options);
     }
 
+    /**
+     * Get a list of sub accounts.
+     *
+     * @param enabled Optional. Whether to fetch enabled or disabled accounts. Default is all.
+     * @param ids     Optional. List of sub-account IDs. Up to 100. When provided, other filters are ignored.
+     * @param prefix  Optional. Search by prefix of the sub-account name. Case-insensitive.
+     * @return the list of sub-accounts details.
+     * @throws Exception If the request fails
+     */
+    public ApiResponse subAccounts(Boolean enabled, List<String> ids, String prefix) throws Exception {
+        return subAccounts(enabled, ids, prefix, Collections.<String, Object>emptyMap());
+    }
+
     /**
      * Get a list of sub accounts.
      *
@@ -125,7 +148,7 @@ public ApiResponse getSubAccount(String subAccountId, Map<String, Object> option
      * @return the list of sub-accounts details.
      * @throws Exception If the request fails
      */
-    public ApiResponse getSubAccounts(Boolean enabled, List<String> ids, String prefix, Map<String, Object> options) throws Exception {
+    public ApiResponse subAccounts(Boolean enabled, List<String> ids, String prefix, Map<String, Object> options) throws Exception {
         List<String> uri = Arrays.asList(PROVISIONING, ACCOUNTS, accountId, "sub_accounts");
         return callAccountApi(Api.HttpMethod.GET, uri,
                 ObjectUtils.asMap("accountId", accountId, "enabled", enabled, "ids", ids, "prefix", prefix), options);
@@ -134,7 +157,20 @@ public ApiResponse getSubAccounts(Boolean enabled, List<String> ids, String pref
     /**
      * @param name             Required. The name displayed in the management console.
      * @param cloudName        Optional, unique (case insensitive)
-     * @param customAttributes Advanced custom attributes for the sub-account.
+     * @param customAttributes Custom attributes associated with the sub-account, as a map of key/value pairs.
+     * @param enabled          Optional. Whether to create the account as enabled (default is enabled).
+     * @param baseAccount      Optional. ID of sub-account from which to copy settings
+     * @return details of the created sub-account
+     * @throws Exception If the request fails
+     */
+    public ApiResponse createSubAccount(String name, String cloudName, Map customAttributes, boolean enabled, String baseAccount) throws Exception {
+        return createSubAccount(name, cloudName, customAttributes, enabled, baseAccount, Collections.<String, Object>emptyMap());
+    }
+
+    /**
+     * @param name             Required. The name displayed in the management console.
+     * @param cloudName        Optional, unique (case insensitive)
+     * @param customAttributes Custom attributes associated with the sub-account, as a map of key/value pairs.
      * @param enabled          Optional. Whether to create the account as enabled (default is enabled).
      * @param baseAccount      Optional. ID of sub-account from which to copy settings
      * @param options          Generic advanced options map, see online documentation.
@@ -160,7 +196,20 @@ public ApiResponse createSubAccount(String name, String cloudName, Map customAtt
      * @param subAccountId     The id of the sub-account to update
      * @param name             The name displayed in the management console.
      * @param cloudName        The cloud name to set.
-     * @param customAttributes Advanced custom attributes for the sub-account.
+     * @param customAttributes ACustom attributes associated with the sub-account, as a map of key/value pairs.
+     * @param enabled          Set the sub-account as enabled or not.
+     * @return details of the updated sub-account
+     * @throws Exception If the request fails
+     */
+    public ApiResponse updateSubAccount(String subAccountId, String name, String cloudName, Map<String, String> customAttributes, Boolean enabled) throws Exception {
+        return updateSubAccount(subAccountId, name, cloudName, customAttributes, enabled, Collections.<String, Object>emptyMap());
+    }
+
+    /**
+     * @param subAccountId     The id of the sub-account to update
+     * @param name             The name displayed in the management console.
+     * @param cloudName        The cloud name to set.
+     * @param customAttributes ACustom attributes associated with the sub-account, as a map of key/value pairs.
      * @param enabled          Set the sub-account as enabled or not.
      * @param options          Generic advanced options map, see online documentation.
      * @return details of the updated sub-account
@@ -180,6 +229,17 @@ public ApiResponse updateSubAccount(String subAccountId, String name, String clo
                 options);
     }
 
+    /**
+     * Deletes the sub-account.
+     *
+     * @param subAccountId The id of the sub-account to delete
+     * @return result message.
+     * @throws Exception If the request fails.
+     */
+    public ApiResponse deleteSubAccount(String subAccountId) throws Exception {
+        return deleteSubAccount(subAccountId, Collections.<String, Object>emptyMap());
+    }
+
     /**
      * Deletes the sub-account.
      *
@@ -194,6 +254,16 @@ public ApiResponse deleteSubAccount(String subAccountId, Map<String, Object> opt
     }
 
     // Users
+    /**
+     * Get details of a specific user.
+     *
+     * @param userId  The id of the user to fetch
+     * @return details of the user.
+     * @throws Exception If the request fails.
+     */
+    public ApiResponse user(String userId) throws Exception {
+        return user(userId,null);
+    }
 
     /**
      * Get details of a specific user.
@@ -203,11 +273,25 @@ public ApiResponse deleteSubAccount(String subAccountId, Map<String, Object> opt
      * @return details of the user.
      * @throws Exception If the request fails.
      */
-    public ApiResponse getUser(String userId, Map<String, Object> options) throws Exception {
+    public ApiResponse user(String userId, Map<String, Object> options) throws Exception {
         List<String> uri = Arrays.asList(PROVISIONING, ACCOUNTS, accountId, USERS, userId);
         return callAccountApi(Api.HttpMethod.GET, uri, Collections.<String, Object>emptyMap(), options);
     }
 
+    /**
+     * Get a list of the users according to filters.
+     *
+     * @param pending      Optional. Whether to fetch pending users. Default all.
+     * @param userIds      Optionals. List of user IDs. Up to 100
+     * @param prefix       Optional. Search by prefix of the user's name or email. Case-insensitive
+     * @param subAccountId Optional. Return only users who have access to the given sub-account
+     * @return the users' details.
+     * @throws Exception If the request fails.
+     */
+    public ApiResponse users(Boolean pending, List<String> userIds, String prefix, String subAccountId) throws Exception {
+        return users(pending, userIds, prefix, subAccountId,null);
+    }
+
     /**
      * Get a list of the users according to filters.
      *
@@ -219,7 +303,7 @@ public ApiResponse getUser(String userId, Map<String, Object> options) throws Ex
      * @return the users' details.
      * @throws Exception If the request fails.
      */
-    public ApiResponse getUsers(Boolean pending, List<String> userIds, String prefix, String subAccountId, Map<String, Object> options) throws Exception {
+    public ApiResponse users(Boolean pending, List<String> userIds, String prefix, String subAccountId, Map<String, Object> options) throws Exception {
         List<String> uri = Arrays.asList(PROVISIONING, ACCOUNTS, accountId, USERS);
         return callAccountApi(Api.HttpMethod.GET, uri,
                 ObjectUtils.asMap("accountId", accountId,
@@ -229,6 +313,21 @@ public ApiResponse getUsers(Boolean pending, List<String> userIds, String prefix
                         "sub_account_id", subAccountId), options);
     }
 
+    /**
+     * Create a new user.
+     *
+     * @param name           Required. Username.
+     * @param email          Required. User's email.
+     * @param role           Required. User's role.
+     * @param subAccountsIds Optional. Sub-accounts for which the user should have access.
+     *                       If not provided or empty, user should have access to all accounts.
+     * @return The newly created user details.
+     * @throws Exception If the request fails.
+     */
+    public ApiResponse createUser(String name, String email, Role role, List<String> subAccountsIds) throws Exception {
+        return createUser(name, email, role, subAccountsIds);
+    }
+
     /**
      * Create a new user.
      *
@@ -254,7 +353,23 @@ public ApiResponse createUser(String name, String email, Role role, List<String>
      * @param email          User's email.
      * @param role           User's role.
      * @param subAccountsIds Sub-accounts for which the user should have access.
-     *                       *                       If not provided or empty, user should have access to all accounts.
+     *                       If not provided or empty, user should have access to all accounts.
+     * @return The updated user details
+     * @throws Exception If the request fails.
+     */
+    public ApiResponse updateUser(String userId, String name, String email, Role role, List<String> subAccountsIds) throws Exception {
+        return updateUser(userId, name, email, role, subAccountsIds,null);
+    }
+
+    /**
+     * Update an existing user.
+     *
+     * @param userId         The id of the user to update.
+     * @param name           Username.
+     * @param email          User's email.
+     * @param role           User's role.
+     * @param subAccountsIds Sub-accounts for which the user should have access.
+     *                       If not provided or empty, user should have access to all accounts.
      * @param options        Generic advanced options map, see online documentation.
      * @return The updated user details
      * @throws Exception If the request fails.
@@ -264,6 +379,17 @@ public ApiResponse updateUser(String userId, String name, String email, Role rol
         return performUserAction(Api.HttpMethod.PUT, uri, email, name, role, subAccountsIds, options);
     }
 
+    /**
+     * Delete a user.
+     *
+     * @param userId  Id of the user to delete.
+     * @return result message.
+     * @throws Exception
+     */
+    public ApiResponse deleteUser(String userId) throws Exception {
+        return deleteUser(userId,null);
+    }
+
     /**
      * Delete a user.
      *
@@ -278,6 +404,15 @@ public ApiResponse deleteUser(String userId, Map<String, Object> options) throws
     }
 
     // Groups
+    /**
+     * Create a new user group
+     * @param name Required. Name for the group.
+     * @return The newly created group.
+     * @throws Exception If the request fails
+     */
+    public ApiResponse createUserGroup(String name) throws Exception {
+        return createUserGroup(name,null);
+    }
 
     /**
      * Create a new user group
@@ -291,6 +426,18 @@ public ApiResponse createUserGroup(String name, Map<String, Object> options) thr
         return callAccountApi(Api.HttpMethod.POST, uri, ObjectUtils.asMap("name", name), options);
     }
 
+    /**
+     * Update an existing user group
+     *
+     * @param groupId The id of the group to update
+     * @param name The name of the group.
+     * @return The updated group.
+     * @throws Exception If the request fails
+     */
+    public ApiResponse updateUserGroup(String groupId, String name) throws Exception {
+        return updateUserGroup(groupId, name,null);
+    }
+
     /**
      * Update an existing user group
      *
@@ -305,6 +452,17 @@ public ApiResponse updateUserGroup(String groupId, String name, Map<String, Obje
         return callAccountApi(Api.HttpMethod.PUT, uri, ObjectUtils.asMap("name", name), options);
     }
 
+    /**
+     * Delete a user group
+     *
+     * @param groupId The group id to delete
+     * @return A result message.
+     * @throws Exception if the request fails.
+     */
+    public ApiResponse deleteUserGroup(String groupId) throws Exception {
+        return deleteUserGroup(groupId,null);
+    }
+
     /**
      * Delete a user group
      *
@@ -318,6 +476,15 @@ public ApiResponse deleteUserGroup(String groupId, Map<String, Object> options)
         return callAccountApi(Api.HttpMethod.DELETE, uri, Collections.<String, Object>emptyMap(), options);
     }
 
+    /**
+     * Add an existing user to a group.
+     * @param groupId The group id.
+     * @param userId The user id to add.
+     * @throws Exception If the request fails
+     */
+    public ApiResponse addUserToGroup(String groupId, String userId) throws Exception {
+        return addUserToGroup(groupId, userId,null);
+    }
     /**
      * Add an existing user to a group.
      * @param groupId The group id.
@@ -330,6 +497,16 @@ public ApiResponse addUserToGroup(String groupId, String userId, Map<String, Obj
         return callAccountApi(Api.HttpMethod.POST, uri, Collections.<String, Object>emptyMap(), options);
     }
 
+    /**
+     * Removes a user from a group.
+     * @param groupId The group id.
+     * @param userId The id of the user to remove
+     * @return A result message
+     * @throws Exception If the request fails.
+     */
+    public ApiResponse removeUserFromGroup(String groupId, String userId) throws Exception {
+        return removeUserFromGroup(groupId, userId,null);
+    }
     /**
      * Removes a user from a group.
      * @param groupId The group id.
@@ -343,6 +520,16 @@ public ApiResponse removeUserFromGroup(String groupId, String userId, Map<String
         return callAccountApi(Api.HttpMethod.DELETE, uri, Collections.<String, Object>emptyMap(), options);
     }
 
+    /**
+     * Get details of a group.
+     * @param groupId The group id to fetch
+     * @return Details of the group.
+     * @throws Exception If the request fails.
+     */
+    public ApiResponse userGroup(String groupId) throws Exception {
+        return userGroup(groupId,null);
+    }
+
     /**
      * Get details of a group.
      * @param groupId The group id to fetch
@@ -350,22 +537,40 @@ public ApiResponse removeUserFromGroup(String groupId, String userId, Map<String
      * @return Details of the group.
      * @throws Exception If the request fails.
      */
-    public ApiResponse getUserGroup(String groupId, Map<String, Object> options) throws Exception {
+    public ApiResponse userGroup(String groupId, Map<String, Object> options) throws Exception {
         List<String> uri = Arrays.asList(PROVISIONING, ACCOUNTS, accountId, USER_GROUPS, groupId);
         return callAccountApi(Api.HttpMethod.GET, uri, Collections.<String, Object>emptyMap(), options);
     }
 
+    /**
+     * Gets a list of all the user groups.
+     * @return The list of the groups.
+     * @throws Exception If the request fails.
+     */
+    public ApiResponse userGroups() throws Exception {
+        return userGroups(Collections.<String, Object>emptyMap());
+    }
+
     /**
      * Gets a list of all the user groups.
      * @param options Generic advanced options map, see online documentation.
      * @return The list of the groups.
      * @throws Exception If the request fails.
      */
-    public ApiResponse listUserGroups(Map<String, Object> options) throws Exception {
+    public ApiResponse userGroups(Map<String, Object> options) throws Exception {
         List<String> uri = Arrays.asList(PROVISIONING, ACCOUNTS, accountId, USER_GROUPS);
         return callAccountApi(Api.HttpMethod.GET, uri, Collections.<String, Object>emptyMap(), options);
     }
 
+    /**
+     * Lists the users belonging to this user group.
+     * @param groupId The id of the user group.
+     * @return The list of users in that group.
+     * @throws Exception If the request fails.
+     */
+    public ApiResponse userGroupUsers(String groupId) throws Exception {
+        return userGroupUsers(groupId,null);
+    }
     /**
      * Lists the users belonging to this user group.
      * @param groupId The id of the user group.
@@ -373,7 +578,7 @@ public ApiResponse listUserGroups(Map<String, Object> options) throws Exception
      * @return The list of users in that group.
      * @throws Exception If the request fails.
      */
-    public ApiResponse listUserGroupUsers(String groupId, Map<String, Object> options) throws Exception {
+    public ApiResponse userGroupUsers(String groupId, Map<String, Object> options) throws Exception {
         List<String> uri = Arrays.asList(PROVISIONING, ACCOUNTS, accountId, USER_GROUPS, groupId, USERS);
         return callAccountApi(Api.HttpMethod.GET, uri, Collections.<String, Object>emptyMap(), options);
     }
@@ -403,7 +608,7 @@ private ApiResponse performUserAction(Api.HttpMethod method, List<String> uri, S
     }
 
     private Map<String, Object> verifyOptions(Map<String, Object> options) {
-        if (options == null) {
+        if (options == null || options == Collections.EMPTY_MAP) {
             return new HashMap<String, Object>(2); // Two, since api key and secret will be populated later
         }
 
diff --git a/cloudinary-test-common/src/main/java/com/cloudinary/test/AbstractAccountApiTest.java b/cloudinary-test-common/src/main/java/com/cloudinary/test/AbstractAccountApiTest.java
index 84256507..17289400 100644
--- a/cloudinary-test-common/src/main/java/com/cloudinary/test/AbstractAccountApiTest.java
+++ b/cloudinary-test-common/src/main/java/com/cloudinary/test/AbstractAccountApiTest.java
@@ -70,14 +70,14 @@ public void testPassingCredentialsThroughOptions() throws Exception {
 
         Map<String, Object> map = singletonMap("provisioning_api_secret", new Object()) ;
         try {
-            this.account.getSubAccounts(true, null, null, map);
+            this.account.subAccounts(true, null, null, map);
         } catch (IllegalArgumentException ignored){
             exceptions++;
         }
 
         map = singletonMap("provisioning_api_key", new Object()) ;
         try {
-            this.account.getSubAccounts(true, null, null, map);
+            this.account.subAccounts(true, null, null, map);
         } catch (IllegalArgumentException ignored){
             exceptions++;
         }
@@ -87,7 +87,7 @@ public void testPassingCredentialsThroughOptions() throws Exception {
         map.put("provisioning_api_secret", "def");
 
         try {
-            this.account.getSubAccounts(true, null, null, map);
+            this.account.subAccounts(true, null, null, map);
         } catch (Exception ex){
             assertTrue(ex.getMessage().contains("Invalid credentials"));
             exceptions++;
@@ -100,14 +100,14 @@ public void testPassingCredentialsThroughOptions() throws Exception {
     @Test
     public void testGetSubAccount() throws Exception {
         ApiResponse accountResponse = createSubAccount();
-        ApiResponse account = this.account.getSubAccount(accountResponse.get("id").toString(), null);
+        ApiResponse account = this.account.subAccount(accountResponse.get("id").toString(), null);
         assertNotNull(account);
     }
 
     @Test
     public void testGetSubAccounts() throws Exception {
         createSubAccount();
-        ApiResponse accounts = account.getSubAccounts(null, null, null, null);
+        ApiResponse accounts = account.subAccounts(null, null, null, null);
         assertNotNull(accounts);
         assertTrue(((ArrayList) accounts.get("sub_accounts")).size() >= 1);
     }
@@ -151,14 +151,14 @@ public void testDeleteSubAccount() throws Exception {
     @Test
     public void testGetUser() throws Exception {
         ApiResponse user = createUser();
-        ApiResponse result = account.getUser(user.get("id").toString(), null);
+        ApiResponse result = account.user(user.get("id").toString(), null);
         assertNotNull(result);
     }
 
     @Test
     public void testGetUsers() throws Exception {
         createUser(Account.Role.MASTER_ADMIN);
-        ApiResponse result = account.getUsers(null, null, null, null, null);
+        ApiResponse result = account.users(null, null, null, null, null);
         assertNotNull(result);
         assertTrue(((ArrayList) result.get("users")).size() >= 1);
     }
@@ -236,7 +236,7 @@ public void testRemoveUserFromUserGroup() throws Exception {
     @Test
     public void testListUserGroups() throws Exception {
         createGroup();
-        ApiResponse result = account.listUserGroups(null);
+        ApiResponse result = account.userGroups();
         assertNotNull(result);
         assertTrue(((List) result.get("user_groups")).size() >= 1);
     }
@@ -244,7 +244,7 @@ public void testListUserGroups() throws Exception {
     @Test
     public void testListUserGroup() throws Exception {
         ApiResponse group = createGroup();
-        ApiResponse result = account.getUserGroup(group.get("id").toString(), null);
+        ApiResponse result = account.userGroup(group.get("id").toString(), null);
         assertNotNull(result);
     }
 
@@ -258,7 +258,7 @@ public void testListUsersInGroup() throws Exception {
         String user2Id = user2.get("id").toString();
         account.addUserToGroup(groupId, user1Id, null);
         account.addUserToGroup(groupId, user2Id, null);
-        ApiResponse result = account.listUserGroupUsers(groupId, null);
+        ApiResponse result = account.userGroupUsers(groupId, null);
         assertNotNull(result);
         assertTrue(((List) result.get("users")).size() >= 2);
     }
@@ -267,7 +267,7 @@ public void testListUsersInGroup() throws Exception {
     // Helpers
     private ApiResponse createGroup() throws Exception {
         String name = randomLetters();
-        ApiResponse userGroup = account.createUserGroup(name, null);
+        ApiResponse userGroup = account.createUserGroup(name);
         createdGroupIds.add(userGroup.get("id").toString());
         return userGroup;
 
@@ -293,7 +293,7 @@ private ApiResponse createUser(List<String> subAccountsIds, Account.Role role) t
     }
 
     private ApiResponse createSubAccount() throws Exception {
-        ApiResponse subAccount = account.createSubAccount(randomLetters(), null, emptyMap(), true, null, null);
+        ApiResponse subAccount = account.createSubAccount(randomLetters(), null, emptyMap(), true, null);
         createdSubAccountIds.add(subAccount.get("id").toString());
         return subAccount;
     }
