Merge pull request zalando#54 from duergner/writing-some-first-javadocs

Should add some first JavaDoc

src/main/java/org/zalando/stups/tokens/AccessTokens.java

@@ -15,11 +15,74 @@
  */
 package org.zalando.stups.tokens;
 
+/**
+ * Use this interface to get retrieve and invalidate access tokens after having them built using
+ * {@link AccessTokensBuilder}
+ *
+ * In most cases getting the access token string via @{@link AccessTokens#get(Object)} will be
+ * sufficient. The returned string should be used as Bearer token with OAuth2.0 e.g.
+ *
+ * If you need the full access token including issue date as well as expire time you should invoke
+ * {@link AccessTokens#getAccessToken(Object)}.
+ *
+ * If you want to invalidate a specific access token to whatever reasons you can use
+ * {@link AccessTokens#invalidate(Object)}.
+ *
+ * The <i>tokenId</i> object used for all three methods must be an object that is equal to the
+ * object used when defining the token via {@link AccessTokensBuilder#manageToken(Object)}. If you
+ * are referring to tokens by {@link String} simply use a {@link String} with equals characters here.
+ */
 public interface AccessTokens {
+
+    /**
+     * Get a valid and up to date access token for the supplied <i>tokenId</i>. The returned {@link String}
+     * can be used as an OAuth2.0 Bearer token e.g.
+     *
+     * @param tokenId  The <i>tokenId</i> to get the access token for. The supplied <i>tokenId</i>
+     *                 must be equal to the <i>tokenId</i> as supplied on
+     *                 {@link AccessTokensBuilder#manageToken(Object)} with respect to
+     *                 {@link Object#equals(Object)}.
+     * @return A {@link String} representation of the access token for the supplied <i>tokenId</i>.
+     * The return value will always be a non null {@link String}.
+     * @throws AccessTokenUnavailableException Thrown inn case there is no access token available
+     * for the supplied <i>tokenId</i> either because there was no such <i>tokenId</i> configured
+     * or getting one from the authorization server was not possible.
+     */
     String get(Object tokenId) throws AccessTokenUnavailableException;
+
+    /**
+     * Get a full {@link AccessToken} not just the {@link String} representation for the supplied
+     * <i>tokenId</i>.
+     *
+     * @param tokenId  The <i>tokenId</i> to get the access token for. The supplied <i>tokenId</i>
+     *                 must be equal to the <i>tokenId</i> as supplied on
+     *                 {@link AccessTokensBuilder#manageToken(Object)} with respect to
+     *                 {@link Object#equals(Object)}.
+     * @return An {@link AccessToken} for the supplied <i>tokenId</i>. The return value will always
+     * be a non null value.
+     * @throws AccessTokenUnavailableException Thrown inn case there is no access token available
+     * for the supplied <i>tokenId</i> either because there was no such <i>tokenId</i> configured
+     * or getting one from the authorization server was not possible.
+     */
     AccessToken getAccessToken(Object tokenId) throws AccessTokenUnavailableException;
 
+    /**
+     * Invalidate the current {@link AccessToken} stored for the supplied <i>tokenId</i>. This will
+     * cause {@link AccessTokens#get(Object)} and {@link AccessTokens#getAccessToken(Object)} to
+     * throw an {@link AccessTokenUnavailableException} until a new access token for this
+     * <i>tokenId</i> could be fetched from the authorization server.
+     *
+     * @param tokenId   The <i>tokenId</i> to invalidate. If no such <i>tokenId</i> has been
+     *                  configured via the {@link AccessTokensBuilder#manageToken(Object)} method
+     *                  this method will simply be a no-op method.
+     */
     void invalidate(Object tokenId);
 
+    /**
+     * Instruct the underlying implementation to stop refreshing of access tokens.
+     *
+     * PLEASE NOTE: Implementations may choose to invalidate all access tokens when this method has
+     * been invoked.
+     */
     void stop();
 }

src/main/java/org/zalando/stups/tokens/Tokens.java

@@ -19,11 +19,26 @@
 
 import java.net.URI;
 
-
+/**
+ * Use e.g. {@link Tokens#createAccessTokensWithUri(URI)} to create an {@link AccessTokensBuilder}
+ * which can be used to define multiple access tokens via {@link AccessTokensBuilder#manageToken(Object)}
+ * that are managed and refreshed.
+ */
 public final class Tokens {
     private Tokens() {
     }
 
+    /**
+     * Create a new {@link AccessTokensBuilder} which can be used to define multiple <i>tokenId</i>s
+     * which can be used to retrieved access tokens from the supplied <i>accessTokenUri</i> which
+     * may have e.g. different <i>scopes</i>.
+     *
+     * @param accessTokenUri  The <i>accessTokenUri</i> to be used by the {@link AccessTokens}
+     *                        implementation created by the returned {@link AccessTokensBuilder} to
+     *                        get and refresh access tokens for the various defined <i>tokenId</i>s
+     * @return An {@link AccessTokensBuilder} which may be used to configure multiple <i>tokenIds</i>s
+     * with various <i>scopes</i> that are managed and refreshed automatically.
+     */
     public static AccessTokensBuilder createAccessTokensWithUri(final URI accessTokenUri) {
         return new AccessTokensBuilder(notNull("accessTokenUri", accessTokenUri));
     }