(jackrabbit-oak) branch trunk updated: OAK-11610: Clarify null passwords in createUser(...)

[kwin]

This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/jackrabbit-oak.git


The following commit(s) were added to refs/heads/trunk by this push:
     new e292d03752 OAK-11610: Clarify null passwords in createUser(...)
e292d03752 is described below

commit e292d03752872599eede2493448e15b670dd6fa0
Author: Konrad Windszus <k...@apache.org>
AuthorDate: Wed Mar 19 12:22:43 2025 +0100

    OAK-11610: Clarify null passwords in createUser(...)
---
 .../apache/jackrabbit/api/security/user/UserManager.java | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git 
a/oak-jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/user/UserManager.java
 
b/oak-jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/user/UserManager.java
index d7823af21c..1799c349bd 100644
--- 
a/oak-jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/user/UserManager.java
+++ 
b/oak-jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/user/UserManager.java
@@ -167,12 +167,12 @@ public interface UserManager {
     Iterator<Authorizable> findAuthorizables(@NotNull Query query) throws 
RepositoryException;
 
     /**
-     * Creates an User for the given userID / password pair; neither of the
-     * specified parameters can be <code>null</code>.<br>
+     * Creates a user for the given userID / password pair. 
+     * <br>
      * Same as {@link #createUser(String,String,Principal,String)} where
      * the specified userID is equal to the principal name and the intermediate
      * path is <code>null</code>.
-     *
+     
      * @param userID The ID of the new user.
      * @param password The initial password of this user.
      * @return The new <code>User</code>.
@@ -184,11 +184,15 @@ public interface UserManager {
     User createUser(@NotNull String userID, @Nullable String password) throws 
AuthorizableExistsException, RepositoryException;
 
     /**
-     * Creates an User for the given parameters. If the implementation is not
+     * Creates a user for the given parameters. If the implementation is not
      * able to deal with the <code>intermediatePath</code> that parameter 
should
      * be ignored.
-     * Except for the <code>intermediatePath</code>, neither of the specified
+     * Except for the <code>intermediatePath</code> and <code>password</code>, 
neither of the specified
      * parameters can be <code>null</code>.
+     * <p>
+     * The given password may be {@code null} however the behavior
+     * of such users depend on the implementation (usually those users cannot 
be used for authentication but only for impersonation).
+     * Consider using {@link #createSystemUser(String, String)} rather than 
creating a user with a {@code null} password with this method.
      *
      * @param userID The ID of the new user.
      * @param password The initial password of the new user.
@@ -201,6 +205,8 @@ public interface UserManager {
      * in use or another Authorizable with the same principal name exists.
      * @throws RepositoryException If the current Session is
      * not allowed to create users or some another error occurs.
+     * 
+     * @see #createSystemUser(String, String)
      */
     @NotNull
     User createUser(@NotNull String userID, @Nullable String password, 
@NotNull Principal principal,