SONAR-3137,SONAR-2292 Add synchronization of groups, prepare API for future enhancements

5 files changed, 46 insertions, 25 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/security/ExternalGroupsProvider.java b/sonar-plugin-api/src/main/java/org/sonar/api/security/ExternalGroupsProvider.java
index c6f7c501f22..0410b66cc90 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/security/ExternalGroupsProvider.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/security/ExternalGroupsProvider.java
@@ -19,17 +19,20 @@
  */
 package org.sonar.api.security;
 
-import com.google.common.annotations.Beta;
-import org.sonar.api.ServerExtension;
-
 import java.util.Collection;
 
 /**
+ * Note that prefix "do" for names of methods is reserved for future enhancements, thus should not be used in subclasses.
+ *
  * @since 2.14
+ * @see SecurityRealm
  */
-@Beta
-public interface ExternalGroupsProvider extends ServerExtension {
+public abstract class ExternalGroupsProvider {
 
-  Collection<String> doGetGroups(String username);
+  /**
+   * @return list of groups associated with specified user, or null if such user doesn't exist
+   * @throws RuntimeException in case of unexpected error such as connection failure
+   */
+  public abstract Collection<String> doGetGroups(String username);
 
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/security/ExternalUsersProvider.java b/sonar-plugin-api/src/main/java/org/sonar/api/security/ExternalUsersProvider.java
index 5e49ef8116f..00f7dfb4dac 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/security/ExternalUsersProvider.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/security/ExternalUsersProvider.java
@@ -19,15 +19,18 @@
  */
 package org.sonar.api.security;
 
-import com.google.common.annotations.Beta;
-import org.sonar.api.ServerExtension;
-
 /**
+ * Note that prefix "do" for names of methods is reserved for future enhancements, thus should not be used in subclasses.
+ *
  * @since 2.14
+ * @see SecurityRealm
  */
-@Beta
-public interface ExternalUsersProvider extends ServerExtension {
+public abstract class ExternalUsersProvider {
 
-  UserDetails doGetUserDetails(String username);
+  /**
+   * @return details for specified user, or null if such user doesn't exist
+   * @throws RuntimeException in case of unexpected error such as connection failure
+   */
+  public abstract UserDetails doGetUserDetails(String username);
 
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/security/LoginPasswordAuthenticator.java b/sonar-plugin-api/src/main/java/org/sonar/api/security/LoginPasswordAuthenticator.java
index 7160746c8e5..8ca6f97864f 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/security/LoginPasswordAuthenticator.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/security/LoginPasswordAuthenticator.java
@@ -23,14 +23,21 @@ import org.sonar.api.ServerExtension;
 
 /**
  * @since 1.12
+ * @see SecurityRealm
  */
 public interface LoginPasswordAuthenticator extends ServerExtension {
 
   /**
-   * Throws a runtime exception if the authenticator can not be initialized at sonar server startup, eg. if the connection to LDAP server is refused.
+   * @throws RuntimeException if the authenticator can not be initialized at sonar server startup, eg. if the connection to LDAP server is refused
+   * @deprecated in 2.14, but was left for backward compatibility - when this authenticator is not a part of {@link SecurityRealm}, otherwise has no effect and not invoked
    */
+  @Deprecated
   void init();
 
-  boolean authenticate(String login, String password);
-  
-}
\ No newline at end of file
+  /**
+   * @return true, if user was successfully authenticated with specified username and password, false otherwise
+   * @throws RuntimeException in case of unexpected error such as connection failure
+   */
+  boolean authenticate(String username, String password);
+
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/security/Realm.java b/sonar-plugin-api/src/main/java/org/sonar/api/security/SecurityRealm.java
index 5ef15b9238c..f21d4d26946 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/security/Realm.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/security/SecurityRealm.java
@@ -19,14 +19,12 @@
  */
 package org.sonar.api.security;
 
-import com.google.common.annotations.Beta;
 import org.sonar.api.ServerExtension;
 
 /**
  * @since 2.14
  */
-@Beta
-public abstract class Realm implements ServerExtension {
+public abstract class SecurityRealm implements ServerExtension {
 
   /**
    * @return unique name of this realm, e.g. "LDAP"
@@ -35,13 +33,16 @@ public abstract class Realm implements ServerExtension {
     return getClass().getSimpleName();
   }
 
+  /**
+   * Invoked during server startup and can be used to initialize internal state.
+   */
   public void init() {
   }
 
   /**
    * @return {@link LoginPasswordAuthenticator} associated with this realm, never null
    */
-  public abstract LoginPasswordAuthenticator getAuthenticator();
+  public abstract LoginPasswordAuthenticator getLoginPasswordAuthenticator();
 
   /**
    * @return {@link ExternalUsersProvider} associated with this realm, null if not supported
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/security/UserDetails.java b/sonar-plugin-api/src/main/java/org/sonar/api/security/UserDetails.java
index e5a4db4b40f..e3519866a13 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/security/UserDetails.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/security/UserDetails.java
@@ -19,18 +19,18 @@
  */
 package org.sonar.api.security;
 
-import com.google.common.annotations.Beta;
+import com.google.common.base.Objects;
 
 /**
  * This class is not intended to be subclassed by clients.
  *
  * @since 2.14
+ * @see ExternalUsersProvider
  */
-@Beta
-public class UserDetails {
+public final class UserDetails {
 
-  private String name;
-  private String email;
+  private String name = "";
+  private String email = "";
 
   public UserDetails() {
   }
@@ -51,4 +51,11 @@ public class UserDetails {
     return name;
   }
 
+  @Override
+  public String toString() {
+    return Objects.toStringHelper(this)
+        .add("name", name)
+        .add("email", email)
+        .toString();
+  }
 }