Refs #1346 Better error reporting and JavaDocs

modules/core/src/com/haulmont/cuba/core/app/ServerConfig.java

@@ -24,8 +24,8 @@ import com.haulmont.cuba.core.config.defaults.DefaultString;
 public interface ServerConfig extends Config {
 
     /**
-     * @return URL of user session provider - usually the main application core.
-     * This URL is used by modules which don't login themselves but get existing sessions from main app.
+     * @return URL of a user session provider - usually the main middleware unit.
+     * This URL is used by middleware units which don't login themselves but get existing sessions from the main app.
      */
     @Property("cuba.userSessionProviderUrl")
     String getUserSessionProviderUrl();

modules/global/src/com/haulmont/cuba/core/global/PasswordEncryption.java

@@ -11,8 +11,7 @@ import com.haulmont.cuba.security.entity.User;
 import java.util.UUID;
 
 /**
- * Encryption support for hashing passwords and security</br>
- * Used for hashing passwords and check passwords at user logon
+ * Encryption support for hashing passwords.
  *
  * @author artamonov
  * @version $Id$
@@ -22,55 +21,57 @@ public interface PasswordEncryption {
     String NAME = "cuba_PasswordEncryption";
 
     /**
-     * @return Random password with Base64 symbols
+     * @return a random password with Base64 symbols
      */
     String generateRandomPassword();
 
     /**
-     * @return Using hash method
+     * @return a hashing method in use
      */
     HashMethod getHashMethod();
 
     /**
-     * Hash string.
+     * Hashing string with salt.
      *
-     * @param content content for hashing
-     * @return Hash with additional params (such as salt)
+     * @param content string for hashing
+     * @return hash with random salt. If the current HashMethod doesn't support salt, it is set to null.
      */
     HashDescriptor getHash(String content);
 
     /**
-     * Hash password.
+     * Hashing password to store it into DB.
      *
-     * @param userId user id
-     * @param password content for hashing
-     * @return Hash with additional params (such as salt)
+     * @param userId    user id
+     * @param password  content for hashing
+     * @return hash with salt, if it is supported by the current HashMethod
      */
     String getPasswordHash(UUID userId, String password);
 
     /**
-     * Hash string.
+     * Hashing string.
      *
      * @param content content for hashing
      * @param salt    salt
-     * @return Hex string of hash
+     * @return hash with salt, if it is supported by the current HashMethod
      */
     String getHash(String content, String salt);
 
     /**
-     * Hash string without salt.
+     * Hashing string without salt.
+     * This method must be used to encrypt password on a client tier before sending it to the middleware.
      *
      * @param content content for hashing
-     * @return Hex string of hash
+     * @return hash
      */
     String getPlainHash(String content);
 
     /**
-     * Check credentials for user.
+     * Check password for a user.
+     * This method is used on the middleware to compare password passed from a client with the one stored in the DB.
      *
-     * @param user          user
-     * @param givenPassword given password
-     * @return True if access permitted and credentials are valid
+     * @param user      user
+     * @param password  password to check. It must be previously encrypted with {@link #getPlainHash(String)} method.
+     * @return true if the password is valid
      */
-    boolean checkPassword(User user, String givenPassword);
+    boolean checkPassword(User user, String password);
 }

modules/global/src/com/haulmont/cuba/core/sys/PasswordEncryptionImpl.java

@@ -70,7 +70,7 @@ public class PasswordEncryptionImpl implements PasswordEncryption {
     }
 
     @Override
-    public boolean checkPassword(User user, String givenPassword) {
-        return encryptionModule.checkPassword(user, givenPassword);
+    public boolean checkPassword(User user, String password) {
+        return encryptionModule.checkPassword(user, password);
     }
 }

modules/global/src/com/haulmont/cuba/core/sys/SecurityContext.java

@@ -14,7 +14,7 @@ import java.util.UUID;
 /**
  * Holds information about the current user session.
  *
- * <p/>Instances of this class are normally being set in {@link AppContext} by the framework, but also have to be
+ * <p/>Instances of this class are normally set in {@link AppContext} by the framework, but also have to be
  * passed to it in case of manually running new threads. Here is the sample code for an asynchronous execution:
  * <pre>
  *     final SecurityContext securityContext = AppContext.getSecurityContext();

modules/global/src/com/haulmont/cuba/core/sys/encryption/Md5EncryptionModule.java

@@ -48,7 +48,7 @@ public class Md5EncryptionModule implements EncryptionModule {
     }
 
     @Override
-    public boolean checkPassword(User user, String givenPassword) {
-        return StringUtils.equals(user.getPassword(), givenPassword);
+    public boolean checkPassword(User user, String password) {
+        return StringUtils.equals(user.getPassword(), password);
     }
 }

modules/global/src/com/haulmont/cuba/core/sys/encryption/Sha1EncryptionModule.java

@@ -82,8 +82,8 @@ public class Sha1EncryptionModule implements EncryptionModule {
     }
 
     @Override
-    public boolean checkPassword(User user, String givenPassword) {
-        String hashedPassword = getHash(givenPassword, user.getId().toString());
+    public boolean checkPassword(User user, String password) {
+        String hashedPassword = getHash(password, user.getId().toString());
         return StringUtils.equals(hashedPassword, user.getPassword());
     }