Add package/class level javadoc in oauth2-client

Fixes gh-4295

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/AuthorizationRequestUriBuilder.java

@@ -21,9 +21,24 @@ import org.springframework.security.oauth2.core.endpoint.AuthorizationRequestAtt
 import java.net.URI;
 
 /**
+ * Implementations of this interface are responsible for building an <i>OAuth 2.0 Authorization Request</i>,
+ * which is used as the redirect <code>URI</code> to the <i>Authorization Endpoint</i>.
+ *
+ * <p>
+ * The returned redirect <code>URI</code> will include the following parameters as query components to the
+ * <i>Authorization Endpoint</i> (using the &quot;application/x-www-form-urlencoded&quot; format):
+ * <ul>
+ * <li>client identifier (required)</li>
+ * <li>response type (required)</li>
+ * <li>requested scope(s) (optional)</li>
+ * <li>state (recommended)</li>
+ * <li>redirection URI (optional) - the authorization server will send the user-agent back to once access is granted (or denied) by the end-user (resource owner)</li>
+ * </ul>
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see AuthorizationRequestAttributes
+ * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1.1">Section 4.1.1 Authorization Request</a>
  */
 public interface AuthorizationRequestUriBuilder {
 

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/DefaultAuthorizationRequestUriBuilder.java

@@ -15,18 +15,22 @@
  */
 package org.springframework.security.oauth2.client.authentication;
 
+import org.springframework.security.oauth2.core.endpoint.AuthorizationRequestAttributes;
 import org.springframework.security.oauth2.core.endpoint.OAuth2Parameter;
 import org.springframework.security.oauth2.core.endpoint.ResponseType;
-import org.springframework.security.oauth2.core.endpoint.AuthorizationRequestAttributes;
 import org.springframework.web.util.UriComponentsBuilder;
 
 import java.net.URI;
 import java.util.stream.Collectors;
 
 /**
+ * The default implementation of an {@link AuthorizationRequestUriBuilder},
+ * which internally uses an {@link UriComponentsBuilder} to construct the <i>OAuth 2.0 Authorization Request</i>.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see AuthorizationRequestAttributes
+ * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1.1">Section 4.1.1 Authorization Request</a>
  */
 public class DefaultAuthorizationRequestUriBuilder implements AuthorizationRequestUriBuilder {
 

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Support classes/interfaces for authenticating an <i>end-user</i>
+ * with an <i>authorization server</i> using the <i>authorization code grant flow</i>.
+ */
+package org.springframework.security.oauth2.client.authentication;

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistration.java

@@ -25,11 +25,12 @@ import java.util.Collections;
 import java.util.LinkedHashSet;
 import java.util.Set;
 
-
 /**
+ * A representation of a client registration with an <i>OAuth 2.0 Authorization Server</i>.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-2">Section 2 Client Registration</a>
  */
 public class ClientRegistration {
 	private String clientId;

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationProperties.java

@@ -21,9 +21,16 @@ import org.springframework.security.oauth2.core.ClientAuthenticationMethod;
 import java.util.Set;
 
 /**
+ * A convenience class that provides a <i>&quot;flattened&quot;</i> property structure for {@link ClientRegistration}.
+ *
+ * <p>
+ * This class may be used to <i>&quot;bind&quot;</i> property values located in the {@link org.springframework.core.env.Environment}
+ * and then pass it to {@link ClientRegistration.Builder#Builder(ClientRegistrationProperties)}
+ * to construct a {@link ClientRegistration} instance.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see ClientRegistration
  */
 public class ClientRegistrationProperties {
 	private String clientId;

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationRepository.java

@@ -18,9 +18,18 @@ package org.springframework.security.oauth2.client.registration;
 import java.util.List;
 
 /**
+ * Implementations of this interface are responsible for the management of {@link ClientRegistration}'s.
+ *
+ * <p>
+ * The <i>primary</i> client registration information is stored with the associated <i>Authorization Server</i>.
+ * However, there may be uses cases where <i>secondary</i> information may need to be managed
+ * that is not supported (or provided) by the <i>Authorization Server</i>.
+ * This interface provides this capability for managing the <i>primary</i> and <i>secondary</i>
+ * information of a client registration.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see ClientRegistration
  */
 public interface ClientRegistrationRepository {
 

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/InMemoryClientRegistrationRepository.java

@@ -22,9 +22,12 @@ import java.util.List;
 import java.util.Optional;
 
 /**
+ * A basic implementation of a {@link ClientRegistrationRepository} that accepts
+ * a <code>List</code> of {@link ClientRegistration}(s) via it's constructor and stores it <i>in-memory</i>.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see ClientRegistration
  */
 public final class InMemoryClientRegistrationRepository implements ClientRegistrationRepository {
 	private final List<ClientRegistration> clientRegistrations;

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/package-info.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Classes and interfaces related to {@link org.springframework.security.oauth2.client.registration.ClientRegistration}.
+ */
+package org.springframework.security.oauth2.client.registration;

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/AbstractOAuth2UserConverter.java

@@ -25,9 +25,13 @@ import java.io.IOException;
 import java.util.Map;
 
 /**
+ * Base implementation of a {@link Converter} that converts a {@link ClientHttpResponse}
+ * to a specific type of {@link OAuth2User}.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see OAuth2User
+ * @see ClientHttpResponse
  */
 public abstract class AbstractOAuth2UserConverter<T extends OAuth2User> implements Converter<ClientHttpResponse, T> {
 	private final HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter();

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/CustomOAuth2UserConverter.java

@@ -24,9 +24,13 @@ import org.springframework.security.oauth2.core.user.OAuth2User;
 import java.io.IOException;
 
 /**
+ * An implementation of a {@link Converter} that converts a {@link ClientHttpResponse}
+ * to a custom type of {@link OAuth2User}, as supplied via the constructor.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see OAuth2User
+ * @see ClientHttpResponse
  */
 public final class CustomOAuth2UserConverter<T extends OAuth2User> implements Converter<ClientHttpResponse, T> {
 	private final HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter();

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/OAuth2UserConverter.java

@@ -15,6 +15,7 @@
  */
 package org.springframework.security.oauth2.client.user.converter;
 
+import org.springframework.http.client.ClientHttpResponse;
 import org.springframework.security.oauth2.core.user.DefaultOAuth2User;
 import org.springframework.security.oauth2.core.user.OAuth2User;
 import org.springframework.util.Assert;
@@ -22,9 +23,13 @@ import org.springframework.util.Assert;
 import java.util.Map;
 
 /**
+ * An implementation of a {@link AbstractOAuth2UserConverter} that converts
+ * a {@link ClientHttpResponse} to a {@link OAuth2User}.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see OAuth2User
+ * @see ClientHttpResponse
  */
 public final class OAuth2UserConverter extends AbstractOAuth2UserConverter<OAuth2User> {
 	private final String nameAttributeKey;

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/UserInfoConverter.java

@@ -15,15 +15,20 @@
  */
 package org.springframework.security.oauth2.client.user.converter;
 
+import org.springframework.http.client.ClientHttpResponse;
 import org.springframework.security.oauth2.oidc.user.DefaultUserInfo;
 import org.springframework.security.oauth2.oidc.user.UserInfo;
 
 import java.util.Map;
 
 /**
+ * An implementation of a {@link AbstractOAuth2UserConverter} that converts
+ * a {@link ClientHttpResponse} to a {@link UserInfo}.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see UserInfo
+ * @see ClientHttpResponse
  */
 public final class UserInfoConverter extends AbstractOAuth2UserConverter<UserInfo> {
 

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * {@link org.springframework.core.convert.converter.Converter} implementations
+ * for {@link org.springframework.security.oauth2.core.user.OAuth2User}.
+ */
+package org.springframework.security.oauth2.client.user.converter;

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/nimbus/NimbusClientHttpResponse.java

@@ -18,6 +18,7 @@ package org.springframework.security.oauth2.client.user.nimbus;
 import com.nimbusds.oauth2.sdk.http.HTTPResponse;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.client.AbstractClientHttpResponse;
+import org.springframework.http.client.ClientHttpResponse;
 import org.springframework.util.Assert;
 
 import java.io.ByteArrayInputStream;
@@ -26,6 +27,10 @@ import java.io.InputStream;
 import java.nio.charset.Charset;
 
 /**
+ * An implementation of a {@link ClientHttpResponse} which is used by {@link NimbusOAuth2UserService}.
+ *
+ * <p>
+ * <b>NOTE:</b> This class is intended for internal use only.
  *
  * @author Joe Grandja
  * @since 5.0

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/package-info.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Support classes and interfaces related to an <i>OAuth 2.0 User</i>.
+ */
+package org.springframework.security.oauth2.client.user;

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/AuthorizationCodeAuthorizationResponseAttributesConverter.java

@@ -16,16 +16,20 @@
 package org.springframework.security.oauth2.client.web.converter;
 
 import org.springframework.core.convert.converter.Converter;
-import org.springframework.security.oauth2.core.endpoint.OAuth2Parameter;
 import org.springframework.security.oauth2.core.endpoint.AuthorizationCodeAuthorizationResponseAttributes;
+import org.springframework.security.oauth2.core.endpoint.OAuth2Parameter;
 import org.springframework.util.Assert;
 
 import javax.servlet.http.HttpServletRequest;
 
 /**
+ * An implementation of a {@link Converter} that converts an <i>OAuth 2.0 Authorization Code Grant Response</i>
+ * (in the form of a {@link HttpServletRequest}) to a {@link AuthorizationCodeAuthorizationResponseAttributes}.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see AuthorizationCodeAuthorizationResponseAttributes
+ * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1.2">Section 4.1.2 Authorization Code Grant Response</a>
  */
 public final class AuthorizationCodeAuthorizationResponseAttributesConverter implements Converter<HttpServletRequest, AuthorizationCodeAuthorizationResponseAttributes> {
 

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/ErrorResponseAttributesConverter.java

@@ -23,9 +23,12 @@ import org.springframework.util.StringUtils;
 import javax.servlet.http.HttpServletRequest;
 
 /**
+ * An implementation of a {@link Converter} that converts an <i>OAuth 2.0 Error Response</i>
+ * (in the form of a {@link HttpServletRequest}) to a {@link ErrorResponseAttributes}.
  *
  * @author Joe Grandja
  * @since 5.0
+ * @see ErrorResponseAttributes
  */
 public final class ErrorResponseAttributesConverter implements Converter<HttpServletRequest, ErrorResponseAttributes> {
 

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * {@link org.springframework.core.convert.converter.Converter} implementations
+ * for <i>OAuth 2.0 Protocol Endpoint Messages</i>.
+ */
+package org.springframework.security.oauth2.client.web.converter;