add: method IAuthenticationService.tryGetAndAuthenticateUserByEmail()

SVN: 17162

authentication/source/java/ch/systemsx/cisd/authentication/DummyAuthenticationService.java

@@ -74,6 +74,13 @@ public final class DummyAuthenticationService implements IAuthenticationService
         return principal;
     }
 
+    public Principal tryGetAndAuthenticateUserByEmail(String applicationToken, String email, String passwordOrNull)
+    {
+        final Principal principal = getPrincipal(applicationToken, email);
+        principal.setAuthenticated(true);
+        return principal;
+    }
+
     public boolean isRemote()
     {
         return false;

authentication/source/java/ch/systemsx/cisd/authentication/IAuthenticationService.java

@@ -80,8 +80,7 @@ public interface IAuthenticationService extends ISelfTestable
      * </p>
      * 
      * @return The <code>Principal</code> object for the given <var>user</var>.
-     * @throws IllegalArgumentException If either the <var>applicationToken</var> is invalid or the
-     *             <var>user</var> cannot be found.
+     * @throws IllegalArgumentException If the <var>user</var> cannot be found.
      */
     public Principal getPrincipal(String applicationToken, String user)
             throws IllegalArgumentException;
@@ -100,7 +99,6 @@ public interface IAuthenticationService extends ISelfTestable
      *            <code>*</code>).
      * @throws UnsupportedOperationException if this authentication service does not support this
      *             operation.
-     * @throws IllegalArgumentException If the <var>applicationToken</var> is invalid.
      */
     public List<Principal> listPrincipalsByUserId(String applicationToken, String userIdQuery)
             throws IllegalArgumentException;
@@ -111,6 +109,29 @@ public interface IAuthenticationService extends ISelfTestable
      */
     public boolean supportsListingByEmail();
 
+    /**
+     * Returns the user details for the given <var>email</var>, optionally trying to authenticating
+     * the user with the given <var>passwordOrNull</var>.
+     * <p>
+     * <b>Note: if multiple users with this email address exist in the authentication repository,
+     * the first one regarding an arbitrary (repository determined) order will be returned.</b>
+     * 
+     * @param applicationToken The token to authenticate the application towards the authentication
+     *            system.
+     * @param email The email of the user to get the details for.
+     * @param passwordOrNull The password to use for the authentication request. If
+     *            <code>null</code>, the user will not be authenticated.
+     * @return The Principal object, if a user with this <var>email</var> exist, <code>null</code>
+     *         otherwise. You can check with {@link Principal#isAuthenticated()} or
+     *         {@link Principal#isAuthenticated(Principal)} whether the authentication request has
+     *         been successful.
+     * @throws UnsupportedOperationException if this authentication service does not support this
+     *             operation.
+     * @throws IllegalArgumentException If the <var>applicationToken</var> is invalid.
+     */
+    public Principal tryGetAndAuthenticateUserByEmail(String applicationToken, String email,
+            String passwordOrNull);
+
     /**
      * Returns a list of all users that match the <var>emailQuery</var>.
      * 

authentication/source/java/ch/systemsx/cisd/authentication/NullAuthenticationService.java

@@ -45,6 +45,11 @@ public class NullAuthenticationService implements IAuthenticationService
         throw new UnsupportedOperationException();
     }
 
+    public Principal tryGetAndAuthenticateUserByEmail(String applicationToken, String email, String passwordOrNull)
+    {
+        throw new UnsupportedOperationException();
+    }
+
     public Principal getPrincipal(String applicationToken, String user)
     {
         throw new UnsupportedOperationException();

authentication/source/java/ch/systemsx/cisd/authentication/crowd/CrowdAuthenticationService.java

@@ -448,6 +448,11 @@ public class CrowdAuthenticationService implements IAuthenticationService
         throw new UnsupportedOperationException();
     }
 
+    public Principal tryGetAndAuthenticateUserByEmail(String applicationToken, String email, String passwordOrNull)
+    {
+        throw new UnsupportedOperationException();
+    }
+
     public List<Principal> listPrincipalsByLastName(String applicationToken, String lastNameQuery)
     {
         throw new UnsupportedOperationException();

authentication/source/java/ch/systemsx/cisd/authentication/file/FileAuthenticationService.java

@@ -130,6 +130,11 @@ public class FileAuthenticationService implements IAuthenticationService
         return principalOrNull;
     }
 
+    public Principal tryGetAndAuthenticateUserByEmail(String applicationToken, String email, String passwordOrNull)
+    {
+        throw new UnsupportedOperationException();
+    }
+
     public List<Principal> listPrincipalsByEmail(String applicationToken, String emailQuery)
     {
         throw new UnsupportedOperationException();

authentication/source/java/ch/systemsx/cisd/authentication/ldap/LDAPAuthenticationService.java

@@ -71,6 +71,11 @@ public class LDAPAuthenticationService implements IAuthenticationService
         return query.listPrincipalsByEmail(emailQuery);
     }
 
+    public Principal tryGetAndAuthenticateUserByEmail(String applicationToken, String email, String passwordOrNull)
+    {
+        return query.tryGetAndAuthenticatePrincipalByEmail(email, passwordOrNull);
+    }
+
     public List<Principal> listPrincipalsByLastName(String applicationToken, String lastNameQuery)
     {
         return query.listPrincipalsByLastName(lastNameQuery);

authentication/source/java/ch/systemsx/cisd/authentication/ldap/LDAPPrincipalQuery.java

@@ -180,6 +180,23 @@ public final class LDAPPrincipalQuery implements ISelfTestable
         {
             return null;
         }
+        authenticatePrincipal(principal, passwordOrNull);
+        return principal;
+    }
+
+    public Principal tryGetAndAuthenticatePrincipalByEmail(String email, String passwordOrNull)
+    {
+        final Principal principal = tryGetPrincipalByEmail(email);
+        if (principal == null)
+        {
+            return null;
+        }
+        authenticatePrincipal(principal, passwordOrNull);
+        return principal;
+    }
+
+    private void authenticatePrincipal(final Principal principal, String passwordOrNull)
+    {
         final String distinguishedName = principal.getProperty(DISTINGUISHED_NAME_ATTRIBUTE_NAME);
         final boolean authenticated =
                 (passwordOrNull == null) ? false : authenticateUserByDistinguishedName(
@@ -187,10 +204,9 @@ public final class LDAPPrincipalQuery implements ISelfTestable
         principal.setAuthenticated(authenticated);
         if (operationLog.isDebugEnabled() && passwordOrNull != null)
         {
-            operationLog.debug(String.format(LOGIN_DN_MSG_TEMPLATE, userId, distinguishedName,
-                    getStatus(authenticated)));
+            operationLog.debug(String.format(LOGIN_DN_MSG_TEMPLATE, principal.getUserId(),
+                    distinguishedName, getStatus(authenticated)));
         }
-        return principal;
     }
 
     private String getStatus(final boolean status)

authentication/source/java/ch/systemsx/cisd/authentication/stacked/StackedAuthenticationService.java

@@ -120,6 +120,23 @@ public class StackedAuthenticationService implements IAuthenticationService
         return null;
     }
 
+    public Principal tryGetAndAuthenticateUserByEmail(String applicationToken, String email, String passwordOrNull)
+    {
+        checkAuthenticatedApplication();
+        int i = 0;
+        for (IAuthenticationService service : delegates)
+        {
+            final String token = tokens.get(i);
+            final Principal principal = service.tryGetAndAuthenticateUserByEmail(token, email, passwordOrNull);
+            if (principal != null)
+            {
+                return principal;
+            }
+            ++i;
+        }
+        return null;
+    }
+
     public List<Principal> listPrincipalsByEmail(String applicationToken, String emailQuery)
     {
         if (supportsListingByEmail == false)