svn commit: r1469391 - /jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenProvider.java

[an...@apache.org]

Author: angela
Date: Thu Apr 18 15:58:11 2013
New Revision: 1469391

URL: http://svn.apache.org/r1469391
Log:
OAK-91 : Implement Authentication Support (javadoc, annotations)

Modified:
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenProvider.java

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenProvider.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenProvider.java?rev=1469391&r1=1469390&r2=1469391&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenProvider.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenProvider.java Thu Apr 18 15:58:11 2013
@@ -18,10 +18,11 @@ package org.apache.jackrabbit.oak.spi.se
 
 import java.util.Map;
 import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
 import javax.jcr.Credentials;
 
 /**
- * TokenProvider... TODO
+ * Interface to manage create and manage login tokens.
  */
 public interface TokenProvider {
 
@@ -39,18 +40,71 @@ public interface TokenProvider {
      */
     String PARAM_TOKEN_LENGTH = "tokenLength";
 
-    boolean doCreateToken(Credentials credentials);
+    /**
+     * Returns {@code true} if the given credentials indicate that a new token
+     * needs to be issued.
+     *
+     * @param credentials The current credentials.
+     * @return {@code true} if a new login token needs to be created, {@code false} otherwise.
+     */
+    boolean doCreateToken(@Nonnull Credentials credentials);
 
+    /**
+     * Issues a new login token for the user with the specified credentials
+     * and returns the associated {@code TokenInfo}.
+     *
+     * @param credentials The current credentials.
+     * @return The {@code TokenInfo} associated with the new login token or
+     * {@code null} if no token has been created.
+     */
     @CheckForNull
-    TokenInfo createToken(Credentials credentials);
+    TokenInfo createToken(@Nonnull Credentials credentials);
 
+    /**
+     * Issues a new login token for the user with the given {@code userId}
+     * and the specified attributes.
+     *
+     * @param userId The identifier of the user for which a new token should
+     * be created.
+     * @param attributes The attributes associated with the new token.
+     * @return The {@code TokenInfo} associated with the new login token or
+     * {@code null} if no token has been created.
+     */
     @CheckForNull
-    TokenInfo createToken(String userId, Map<String,?> attributes);
+    TokenInfo createToken(@Nonnull String userId, @Nonnull Map<String,?> attributes);
 
+    /**
+     * Retrieves the {@code TokenInfo} associated with the specified login token
+     * or {@code null}.
+     *
+     * @param token A valid login token.
+     * @return the {@code TokenInfo} associated with the specified login token
+     * or {@code null}.
+     */
     @CheckForNull
-    TokenInfo getTokenInfo(String token);
+    TokenInfo getTokenInfo(@Nonnull String token);
 
-    boolean removeToken(TokenInfo tokenInfo);
+    /**
+     * Tries to remove the login token and all related information. This method
+     * returns {@code true} if the removal was successful.
+     *
+     * @param tokenInfo The {@code TokenInfo} associated with the login token to
+     * be removed.
+     * @return {@code true} if the removal was successful, {@code false} otherwise.
+     */
+    boolean removeToken(@Nonnull TokenInfo tokenInfo);
 
-    boolean resetTokenExpiration(TokenInfo tokenInfo, long loginTime);
+    /**
+     * Resets the expiration time of the login token associated with the given
+     * {@code TokenInfo}. Whether and when the expiration time of a given login
+     * token is being reset is an implementation detail. Implementations that
+     * don't allow for resetting the token's expiration time at all will always
+     * return {@code false}.
+     *
+     * @param tokenInfo The {@code TokenInfo} associated with the login token to
+     * be reset.
+     * @param loginTime The current login time.
+     * @return {@code true} if the expiration time has been reset, false otherwise.
+     */
+    boolean resetTokenExpiration(@Nonnull TokenInfo tokenInfo, long loginTime);
 }