#782 Deprecate user manager API

src/docs/asciidoc/release_notes.adoc

@@ -921,6 +921,9 @@ This change was backported to Jaybird 5.0.4.
 +
 If the best row identifier was not matched, but the result set contains `RDB$DB_KEY`, we will now consider the result set updatable.
 However, if the table in question has a primary key, and the columns missing from the result set are not generated, this may still fail when calling `ResultSet.insertRow()`.
+* The user manager API (`UserManager`/`FBUserManager` and `User`/`FBUser`) has been deprecated (https://github.com/FirebirdSQL/jaybird/issues/782[#782])
++
+We do not plan to remove this API at this time, but we recommend that you switch to using the SQL user management statements.
 
 [#potentially-breaking-changes]
 === Potentially breaking changes

src/main/org/firebirdsql/management/FBUser.java

@@ -25,28 +25,35 @@
  *
  * @author Steven Jardine
  * @author Roman Rokytskyy
+ * @deprecated Use the SQL user management statements instead, we currently do not plan to remove this API
  */
+@Deprecated(since = "6")
+@SuppressWarnings("DeprecatedIsStillUsed")
 public class FBUser implements User {
 
-    private String userName = null;
-
-    private String password = null;
-
-    private String firstName = null;
-
-    private String middleName = null;
-
-    private String lastName = null;
-
+    private String userName;
+    private String password;
+    private String firstName;
+    private String middleName;
+    private String lastName;
     private int userId = -1;
-
     private int groupId = -1;
 
     /**
      * Create an instance of this class.
      */
     public FBUser() {
-        super();
+    }
+
+    FBUser(String userName, String password, String firstName, String middleName, String lastName, int userId,
+            int groupId) {
+        this.userName = userName;
+        this.password = password;
+        this.firstName = firstName;
+        this.middleName = middleName;
+        this.lastName = lastName;
+        this.userId = userId;
+        this.groupId = groupId;
     }
 
     @Override
@@ -122,12 +129,8 @@ public void setGroupId(int groupId) {
     @Override
     public boolean equals(Object obj) {
         if (obj == this) return true;
-
-        if (!(obj instanceof User))
-            return false;
-
-        User user = (User) obj;
-        return Objects.equals(getUserName(), user.getUserName())
+        return obj instanceof User user
+                && Objects.equals(getUserName(), user.getUserName())
                 && Objects.equals(getFirstName(), user.getFirstName())
                 && Objects.equals(getMiddleName(), user.getMiddleName())
                 && Objects.equals(getLastName(), user.getLastName())

src/main/org/firebirdsql/management/FBUserManager.java

@@ -38,7 +38,10 @@
  *
  * @author Steven Jardine
  * @author Mark Rotteveel
+ * @deprecated Use the SQL user management statements instead, we currently do not plan to remove this API
  */
+@Deprecated(since = "6")
+@SuppressWarnings("DeprecatedIsStillUsed")
 public class FBUserManager extends FBServiceManager implements UserManager {
 
     private int count = 0;
@@ -81,49 +84,31 @@ public FBUserManager(GDSType gdsType) {
      * @return a map of users parsed from the display buffer.
      */
     private Map<String, User> getFBUsers() {
-        User user = null;
         Map<String, User> users = new TreeMap<>();
         byte[] displayBuffer = ((ByteArrayOutputStream) getLogger()).toByteArray();
+        var userBuilder = new FBUserBuilder();
         count = 0;
         while (count < displayBuffer.length && displayBuffer[count] != isc_info_end) {
             switch (displayBuffer[count]) {
-            case isc_spb_sec_username:
-                if (user != null) {
-                    users.put(user.getUserName(), user);
+            case isc_spb_sec_username -> {
+                if (userBuilder.isInitialized()) {
+                    users.put(userBuilder.getUserName(), userBuilder.build());
                 }
-                user = new FBUser();
-                user.setUserName(getSRBString(displayBuffer));
-                break;
-            case isc_spb_sec_firstname:
-                assert user != null : "Should have a non null user";
-                user.setFirstName(getSRBString(displayBuffer));
-                break;
-            case isc_spb_sec_middlename:
-                assert user != null : "Should have a non null user";
-                user.setMiddleName(getSRBString(displayBuffer));
-                break;
-            case isc_spb_sec_lastname:
-                assert user != null : "Should have a non null user";
-                user.setLastName(getSRBString(displayBuffer));
-                break;
-            case isc_spb_sec_userid:
-                assert user != null : "Should have a non null user";
-                user.setUserId(getSRBInteger(displayBuffer));
-                break;
-            case isc_spb_sec_groupid:
-                assert user != null : "Should have a non null user";
-                user.setGroupId(getSRBInteger(displayBuffer));
-                break;
-            default:
-                count++;
-                break;
+                userBuilder.reset();
+                userBuilder.setUserName(getSRBString(displayBuffer));
+            }
+            case isc_spb_sec_firstname -> userBuilder.setFirstName(getSRBString(displayBuffer));
+            case isc_spb_sec_middlename -> userBuilder.setMiddleName(getSRBString(displayBuffer));
+            case isc_spb_sec_lastname -> userBuilder.setLastName(getSRBString(displayBuffer));
+            case isc_spb_sec_userid -> userBuilder.setUserId(getSRBInteger(displayBuffer));
+            case isc_spb_sec_groupid -> userBuilder.setGroupId(getSRBInteger(displayBuffer));
+            default -> count++;
             }
         }
-        if (user != null) {
-            users.put(user.getUserName(), user);
+        if (userBuilder.isInitialized()) {
+            users.put(userBuilder.getUserName(), userBuilder.build());
         }
         return users;
-
     }
 
     /**
@@ -225,31 +210,35 @@ private void userAction(int action, User user) throws SQLException {
         }
     }
 
+    @Override
     public void add(User user) throws SQLException, IOException {
-        if (user.getUserName() == null) {
-            throw new SQLException("UserName is required.");
-        }
+        requireUserName(user);
         userAction(isc_action_svc_add_user, user);
     }
 
+    @Override
     public void delete(User user) throws SQLException, IOException {
-        if (user.getUserName() == null) {
-            throw new SQLException("UserName is required.");
-        }
+        requireUserName(user);
         // Only parameter for delete action is username. All others should be null.
         User delUser = new FBUser();
         delUser.setUserName(user.getUserName());
         userAction(isc_action_svc_delete_user, delUser);
     }
 
+    @Override
     public void update(User user) throws SQLException, IOException {
+        requireUserName(user);
+        userAction(isc_action_svc_modify_user, user);
+    }
+
+    private void requireUserName(User user) throws SQLException {
         if (user.getUserName() == null) {
             throw new SQLException("UserName is required.");
         }
-        userAction(isc_action_svc_modify_user, user);
     }
 
     @SuppressWarnings("RedundantThrows")
+    @Override
     public Map<String, User> getUsers() throws SQLException, IOException {
         OutputStream savedStream = getLogger();
         setLogger(new ByteArrayOutputStream());
@@ -261,6 +250,7 @@ public Map<String, User> getUsers() throws SQLException, IOException {
         }
     }
 
+    @Override
     public void setSecurityDatabase(String securityDatabase) {
         this.securityDatabase = securityDatabase;
     }
@@ -281,12 +271,68 @@ private void adminRoleAction(int action) throws SQLException {
     }
 
     @SuppressWarnings("RedundantThrows")
+    @Override
     public void setAdminRoleMapping() throws SQLException, IOException {
         adminRoleAction(isc_action_svc_set_mapping);
     }
 
     @SuppressWarnings("RedundantThrows")
+    @Override
     public void dropAdminRoleMapping() throws SQLException, IOException {
         adminRoleAction(isc_action_svc_drop_mapping);
     }
+
+    private static final class FBUserBuilder {
+
+        private String userName;
+        private String firstName;
+        private String middleName;
+        private String lastName;
+        private int userId = -1;
+        private int groupId = -1;
+
+        FBUser build() {
+            return new FBUser(userName, null, firstName, middleName, lastName, userId, groupId);
+        }
+
+        /**
+         * @return {@code true} if at least {@code userName} is set, {@code false} otherwise
+         */
+        boolean isInitialized() {
+            return userName != null;
+        }
+
+        void reset() {
+            userName = firstName = middleName = lastName = null;
+            userId = groupId = -1;
+        }
+
+        void setUserName(String userName) {
+            this.userName = userName;
+        }
+
+        String getUserName() {
+            return userName;
+        }
+
+        void setFirstName(String firstName) {
+            this.firstName = firstName;
+        }
+
+        void setMiddleName(String middleName) {
+            this.middleName = middleName;
+        }
+
+        void setLastName(String lastName) {
+            this.lastName = lastName;
+        }
+
+        void setUserId(int userId) {
+            this.userId = userId;
+        }
+
+        void setGroupId(int groupId) {
+            this.groupId = groupId;
+        }
+    }
 }

src/main/org/firebirdsql/management/User.java

@@ -28,7 +28,10 @@
  * A user in the Firebird Security Database.
  *
  * @author Steven Jardine
+ * @deprecated Use the SQL user management statements instead, we currently do not plan to remove this API
  */
+@Deprecated(since = "6")
+@SuppressWarnings("DeprecatedIsStillUsed")
 public interface User {
 
     /**

src/main/org/firebirdsql/management/UserManager.java

@@ -32,7 +32,10 @@
  * The base Firebird Service API functionality.
  *
  * @author Steven Jardine
+ * @deprecated Use the SQL user management statements instead, we currently do not plan to remove this API
  */
+@Deprecated(since = "6")
+@SuppressWarnings("DeprecatedIsStillUsed")
 public interface UserManager extends ServiceManager {
 
     /**