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);
}
