Add javadoc for OAuth2TokenCustomizer

Issue gh-199

Author: jgrandja

oauth2-authorization-server/src/main/java/org/springframework/security/oauth2/core/context/Context.java

@@ -26,16 +26,36 @@
  */
 public interface Context {
 
+	/**
+	 * Returns the value of the attribute associated to the key.
+	 *
+	 * @param key the key for the attribute
+	 * @param <V> the type of the value for the attribute
+	 * @return the value of the attribute associated to the key, or {@code null} if not available
+	 */
 	@Nullable
 	<V> V get(Object key);
 
+	/**
+	 * Returns the value of the attribute associated to the key.
+	 *
+	 * @param key the key for the attribute
+	 * @param <V> the type of the value for the attribute
+	 * @return the value of the attribute associated to the key, or {@code null} if not available or not of the specified type
+	 */
 	@Nullable
 	default <V> V get(Class<V> key) {
 		Assert.notNull(key, "key cannot be null");
 		V value = get((Object) key);
 		return key.isInstance(value) ? value : null;
 	}
 
+	/**
+	 * Returns {@code true} if an attribute associated to the key exists, {@code false} otherwise.
+	 *
+	 * @param key the key for the attribute
+	 * @return {@code true} if an attribute associated to the key exists, {@code false} otherwise
+	 */
 	boolean hasKey(Object key);
 
 }

oauth2-authorization-server/src/main/java/org/springframework/security/oauth2/server/authorization/JwtEncodingContext.java

@@ -22,15 +22,20 @@
 
 import org.springframework.lang.Nullable;
 import org.springframework.security.oauth2.jwt.JoseHeader;
+import org.springframework.security.oauth2.jwt.Jwt;
 import org.springframework.security.oauth2.jwt.JwtClaimsSet;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
 import org.springframework.util.Assert;
 
 /**
+ * An {@link OAuth2TokenContext} implementation used when encoding a {@link Jwt}.
+ *
  * @author Joe Grandja
  * @since 0.1.0
  * @see OAuth2TokenContext
  * @see JoseHeader.Builder
  * @see JwtClaimsSet.Builder
+ * @see JwtEncoder#encode(JoseHeader, JwtClaimsSet)
  */
 public final class JwtEncodingContext implements OAuth2TokenContext {
 	private final Map<Object, Object> context;
@@ -52,18 +57,38 @@ public boolean hasKey(Object key) {
 		return this.context.containsKey(key);
 	}
 
+	/**
+	 * Returns the {@link JoseHeader.Builder headers}.
+	 *
+	 * @return the {@link JoseHeader.Builder}
+	 */
 	public JoseHeader.Builder getHeaders() {
 		return get(JoseHeader.Builder.class);
 	}
 
+	/**
+	 * Returns the {@link JwtClaimsSet.Builder claims}.
+	 *
+	 * @return the {@link JwtClaimsSet.Builder}
+	 */
 	public JwtClaimsSet.Builder getClaims() {
 		return get(JwtClaimsSet.Builder.class);
 	}
 
+	/**
+	 * Constructs a new {@link Builder} with the provided headers and claims.
+	 *
+	 * @param headersBuilder the headers to initialize the builder
+	 * @param claimsBuilder the claims to initialize the builder
+	 * @return the {@link Builder}
+	 */
 	public static Builder with(JoseHeader.Builder headersBuilder, JwtClaimsSet.Builder claimsBuilder) {
 		return new Builder(headersBuilder, claimsBuilder);
 	}
 
+	/**
+	 * A builder for {@link JwtEncodingContext}.
+	 */
 	public static final class Builder extends AbstractBuilder<JwtEncodingContext, Builder> {
 
 		private Builder(JoseHeader.Builder headersBuilder, JwtClaimsSet.Builder claimsBuilder) {
@@ -73,18 +98,39 @@ private Builder(JoseHeader.Builder headersBuilder, JwtClaimsSet.Builder claimsBu
 			put(JwtClaimsSet.Builder.class, claimsBuilder);
 		}
 
+		/**
+		 * A {@code Consumer} of the {@link JoseHeader.Builder headers}
+		 * allowing the ability to add, replace, or remove.
+		 *
+		 * @param headersConsumer a {@code Consumer} of the {@link JoseHeader.Builder headers}
+		 * @return the {@link Builder} for further configuration
+		 */
 		public Builder headers(Consumer<JoseHeader.Builder> headersConsumer) {
 			headersConsumer.accept(get(JoseHeader.Builder.class));
 			return this;
 		}
 
+		/**
+		 * A {@code Consumer} of the {@link JwtClaimsSet.Builder claims}
+		 * allowing the ability to add, replace, or remove.
+		 *
+		 * @param claimsConsumer a {@code Consumer} of the {@link JwtClaimsSet.Builder claims}
+		 * @return the {@link Builder} for further configuration
+		 */
 		public Builder claims(Consumer<JwtClaimsSet.Builder> claimsConsumer) {
 			claimsConsumer.accept(get(JwtClaimsSet.Builder.class));
 			return this;
 		}
 
+		/**
+		 * Builds a new {@link JwtEncodingContext}.
+		 *
+		 * @return the {@link JwtEncodingContext}
+		 */
 		public JwtEncodingContext build() {
 			return new JwtEncodingContext(getContext());
 		}
+
 	}
+
 }

oauth2-authorization-server/src/main/java/org/springframework/security/oauth2/server/authorization/OAuth2TokenContext.java

@@ -30,85 +30,188 @@
 import org.springframework.util.Assert;
 
 /**
+ * A context that holds information associated to an OAuth 2.0 Token
+ * and is used by an {@link OAuth2TokenCustomizer} for customizing the token attributes.
+ *
  * @author Joe Grandja
  * @since 0.1.0
  * @see Context
+ * @see OAuth2TokenCustomizer
  */
 public interface OAuth2TokenContext extends Context {
 
+	/**
+	 * Returns the {@link RegisteredClient registered client}.
+	 *
+	 * @return the {@link RegisteredClient}
+	 */
 	default RegisteredClient getRegisteredClient() {
 		return get(RegisteredClient.class);
 	}
 
+	/**
+	 * Returns the {@link Authentication} representing the {@code Principal} resource owner (or client).
+	 *
+	 * @param <T> the type of the {@code Authentication}
+	 * @return the {@link Authentication} representing the {@code Principal} resource owner (or client)
+	 */
 	default <T extends Authentication> T getPrincipal() {
 		return get(AbstractBuilder.PRINCIPAL_AUTHENTICATION_KEY);
 	}
 
+	/**
+	 * Returns the {@link OAuth2Authorization authorization}.
+	 *
+	 * @return the {@link OAuth2Authorization}, or {@code null} if not available
+	 */
 	@Nullable
 	default OAuth2Authorization getAuthorization() {
 		return get(OAuth2Authorization.class);
 	}
 
+	/**
+	 * Returns the authorized scope(s).
+	 *
+	 * @return the authorized scope(s)
+	 */
 	default Set<String> getAuthorizedScopes() {
 		return hasKey(OAuth2Authorization.AUTHORIZED_SCOPE_ATTRIBUTE_NAME) ?
 				get(OAuth2Authorization.AUTHORIZED_SCOPE_ATTRIBUTE_NAME) :
 				Collections.emptySet();
 	}
 
+	/**
+	 * Returns the {@link OAuth2TokenType token type}.
+	 *
+	 * @return the {@link OAuth2TokenType}
+	 */
 	default OAuth2TokenType getTokenType() {
 		return get(OAuth2TokenType.class);
 	}
 
+	/**
+	 * Returns the {@link AuthorizationGrantType authorization grant type}.
+	 *
+	 * @return the {@link AuthorizationGrantType}
+	 */
 	default AuthorizationGrantType getAuthorizationGrantType() {
 		return get(AuthorizationGrantType.class);
 	}
 
+	/**
+	 * Returns the {@link Authentication} representing the authorization grant.
+	 *
+	 * @param <T> the type of the {@code Authentication}
+	 * @return the {@link Authentication} representing the authorization grant
+	 */
 	default <T extends Authentication> T getAuthorizationGrant() {
 		return get(AbstractBuilder.AUTHORIZATION_GRANT_AUTHENTICATION_KEY);
 	}
 
+	/**
+	 * Base builder for implementations of {@link OAuth2TokenContext}.
+	 *
+	 * @param <T> the type of the context
+	 * @param <B> the type of the builder
+	 */
 	abstract class AbstractBuilder<T extends OAuth2TokenContext, B extends AbstractBuilder<T, B>> {
 		private static final String PRINCIPAL_AUTHENTICATION_KEY =
 				Authentication.class.getName().concat(".PRINCIPAL");
 		private static final String AUTHORIZATION_GRANT_AUTHENTICATION_KEY =
 				Authentication.class.getName().concat(".AUTHORIZATION_GRANT");
 		private final Map<Object, Object> context = new HashMap<>();
 
+		/**
+		 * Sets the {@link RegisteredClient registered client}.
+		 *
+		 * @param registeredClient the {@link RegisteredClient}
+		 * @return the {@link AbstractBuilder} for further configuration
+		 */
 		public B registeredClient(RegisteredClient registeredClient) {
 			return put(RegisteredClient.class, registeredClient);
 		}
 
+		/**
+		 * Sets the {@link Authentication} representing the {@code Principal} resource owner (or client).
+		 *
+		 * @param principal the {@link Authentication} representing the {@code Principal} resource owner (or client)
+		 * @return the {@link AbstractBuilder} for further configuration
+		 */
 		public B principal(Authentication principal) {
 			return put(PRINCIPAL_AUTHENTICATION_KEY, principal);
 		}
 
+		/**
+		 * Sets the {@link OAuth2Authorization authorization}.
+		 *
+		 * @param authorization the {@link OAuth2Authorization}
+		 * @return the {@link AbstractBuilder} for further configuration
+		 */
 		public B authorization(OAuth2Authorization authorization) {
 			return put(OAuth2Authorization.class, authorization);
 		}
 
+		/**
+		 * Sets the authorized scope(s).
+		 *
+		 * @param authorizedScopes the authorized scope(s)
+		 * @return the {@link AbstractBuilder} for further configuration
+		 */
 		public B authorizedScopes(Set<String> authorizedScopes) {
 			return put(OAuth2Authorization.AUTHORIZED_SCOPE_ATTRIBUTE_NAME, authorizedScopes);
 		}
 
+		/**
+		 * Sets the {@link OAuth2TokenType token type}.
+		 *
+		 * @param tokenType the {@link OAuth2TokenType}
+		 * @return the {@link AbstractBuilder} for further configuration
+		 */
 		public B tokenType(OAuth2TokenType tokenType) {
 			return put(OAuth2TokenType.class, tokenType);
 		}
 
+		/**
+		 * Sets the {@link AuthorizationGrantType authorization grant type}.
+		 *
+		 * @param authorizationGrantType the {@link AuthorizationGrantType}
+		 * @return the {@link AbstractBuilder} for further configuration
+		 */
 		public B authorizationGrantType(AuthorizationGrantType authorizationGrantType) {
 			return put(AuthorizationGrantType.class, authorizationGrantType);
 		}
 
+		/**
+		 * Sets the {@link Authentication} representing the authorization grant.
+		 *
+		 * @param authorizationGrant the {@link Authentication} representing the authorization grant
+		 * @return the {@link AbstractBuilder} for further configuration
+		 */
 		public B authorizationGrant(Authentication authorizationGrant) {
 			return put(AUTHORIZATION_GRANT_AUTHENTICATION_KEY, authorizationGrant);
 		}
 
+		/**
+		 * Associates an attribute.
+		 *
+		 * @param key the key for the attribute
+		 * @param value the value of the attribute
+		 * @return the {@link AbstractBuilder} for further configuration
+		 */
 		public B put(Object key, Object value) {
 			Assert.notNull(key, "key cannot be null");
 			Assert.notNull(value, "value cannot be null");
 			this.context.put(key, value);
 			return getThis();
 		}
 
+		/**
+		 * A {@code Consumer} of the attributes {@code Map}
+		 * allowing the ability to add, replace, or remove.
+		 *
+		 * @param contextConsumer a {@link Consumer} of the attributes {@code Map}
+		 * @return the {@link AbstractBuilder} for further configuration
+		 */
 		public B context(Consumer<Map<Object, Object>> contextConsumer) {
 			contextConsumer.accept(this.context);
 			return getThis();
@@ -128,7 +231,13 @@ protected final B getThis() {
 			return (B) this;
 		}
 
+		/**
+		 * Builds a new {@link OAuth2TokenContext}.
+		 *
+		 * @return the {@link OAuth2TokenContext}
+		 */
 		public abstract T build();
 
 	}
+
 }

oauth2-authorization-server/src/main/java/org/springframework/security/oauth2/server/authorization/OAuth2TokenCustomizer.java

@@ -16,13 +16,22 @@
 package org.springframework.security.oauth2.server.authorization;
 
 /**
+ * Implementations of this interface are responsible for customizing the
+ * OAuth 2.0 Token attributes contained within the {@link OAuth2TokenContext}.
+ *
  * @author Joe Grandja
  * @since 0.1.0
  * @see OAuth2TokenContext
+ * @param <C> the type of the context containing the OAuth 2.0 Token attributes
  */
 @FunctionalInterface
 public interface OAuth2TokenCustomizer<C extends OAuth2TokenContext> {
 
+	/**
+	 * Customize the OAuth 2.0 Token attributes.
+	 *
+	 * @param context the context containing the OAuth 2.0 Token attributes
+	 */
 	void customize(C context);
 
 }