added javadocs

pom.xml

@@ -118,6 +118,19 @@
 					</dependency>
 				</dependencies>
 			</plugin>
+			<plugin>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<executions>
+					<execution>
+						<id>javadoc</id>
+						<phase>package</phase>
+						<goals><goal>jar</goal></goals>
+						<configuration>
+							<show>public</show>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
 		</plugins>
 	</build>
 	
@@ -138,4 +151,4 @@
 			<url>https://repos.inteligr8.com/nexus/repository/inteligr8-snapshots</url>
 		</snapshotRepository>
 	</distributionManagement>
-</project>
+</project>

src/main/java/com/inteligr8/rs/AccessTokenRequestFilter.java

@@ -1,19 +0,0 @@
-package com.inteligr8.rs;
-
-import javax.ws.rs.client.ClientRequestContext;
-import javax.ws.rs.core.HttpHeaders;
-
-public class AccessTokenRequestFilter implements AuthorizationFilter {
-	
-	private final String token;
-	
-	public AccessTokenRequestFilter(String token) {
-		this.token = token;
-	}
-	
-	@Override
-	public void filter(ClientRequestContext requestContext) {
-		requestContext.getHeaders().add(HttpHeaders.AUTHORIZATION, "Bearer " + this.token);
-	}
-
-}

src/main/java/com/inteligr8/rs/AuthorizationFilter.java

@@ -2,6 +2,12 @@ package com.inteligr8.rs;
 
 import javax.ws.rs.client.ClientRequestFilter;
 
+/**
+ * This is a marker that allows the developer to segregate, restrict, or limit
+ * authorization specific implementations of the ClientRequestFilter.
+ * 
+ * @author brian@inteligr8.com
+ */
 public interface AuthorizationFilter extends ClientRequestFilter {
 
 }

src/main/java/com/inteligr8/rs/BasicAuthorizationFilter.java

@@ -6,16 +6,32 @@ import java.util.Base64;
 import javax.ws.rs.client.ClientRequestContext;
 import javax.ws.rs.core.HttpHeaders;
 
-public class BasicAuthRequestFilter implements AuthorizationFilter {
+/**
+ * This class implements a simple 2-credential (username & password) based
+ * authorization filter.
+ *  
+ * @author brian@inteligr8.com
+ */
+public class BasicAuthorizationFilter implements AuthorizationFilter {
 	
 	private final String username;
 	private final String password;
 	
-	public BasicAuthRequestFilter(String username, String password) {
+	/**
+	 * @param username A username or access key.
+	 * @param password A password or secret key.
+	 */
+	public BasicAuthorizationFilter(String username, String password) {
 		this.username = username;
 		this.password = password;
 	}
 	
+	/**
+	 * This method applies the 'Authorization' header to the {@link ClientRequestContext}.
+	 * 
+	 * @param requestContext A request context.
+	 * @throws UnsupportedEncodingException The 'utf-8' encoding is not supported.
+	 */
 	@Override
 	public void filter(ClientRequestContext requestContext) throws UnsupportedEncodingException {
 		String userAndPass = this.username + ":" + this.password;

src/main/java/com/inteligr8/rs/BearerTokenAuthorizationFilter.java

@@ -0,0 +1,40 @@
+package com.inteligr8.rs;
+
+import java.io.UnsupportedEncodingException;
+
+import javax.ws.rs.client.ClientRequestContext;
+import javax.ws.rs.core.HttpHeaders;
+
+/**
+ * This class implements a simple long living or proxied token-based
+ * authorization filter.  The token is expected to be acquired outside of the
+ * purview of this library.
+ * 
+ * If you have the full authorization header and not just the bearer token, use
+ * the {@link ForwardingAuthorizationFilter}.
+ *  
+ * @author brian@inteligr8.com
+ */
+public class BearerTokenAuthorizationFilter implements AuthorizationFilter {
+	
+	private final String token;
+	
+	/**
+	 * @param token A 'Bearer' token.
+	 */
+	public BearerTokenAuthorizationFilter(String token) {
+		this.token = token;
+	}
+
+	/**
+	 * This method applies the 'Authorization' header to the {@link ClientRequestContext}.
+	 * 
+	 * @param requestContext A request context.
+	 * @throws UnsupportedEncodingException The 'utf-8' encoding is not supported.
+	 */
+	@Override
+	public void filter(ClientRequestContext requestContext) {
+		requestContext.getHeaders().add(HttpHeaders.AUTHORIZATION, "Bearer " + this.token);
+	}
+
+}

src/main/java/com/inteligr8/rs/Client.java

@@ -6,16 +6,25 @@ import javax.ws.rs.client.WebTarget;
 import com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider;
 
 /**
- * Configured JAX-RS Client & WebTarget
+ * A class that provides pre-configured JAX-RS Client & WebTarget objects.
+ * 
+ * @author brian@inteligr8.com
  */
 public abstract class Client {
 	
 	protected abstract ClientConfiguration getConfig();
 	
+	/**
+	 * @return A pre-configured JAX-RS client (no URL) with configured authorization.
+	 */
 	public final javax.ws.rs.client.Client getClient() {
 		return this.getClient(null);
 	}
 	
+	/**
+	 * @param authFilter A dynamic authorization filter.
+	 * @return A pre-configured JAX-RS client (no URL) with the specified authorization.
+	 */
 	public javax.ws.rs.client.Client getClient(AuthorizationFilter authFilter) {
 		ClientBuilder clientBuilder = ClientBuilder.newBuilder()
 				.register(new JacksonJaxbJsonProvider());
@@ -28,19 +37,40 @@ public abstract class Client {
 		return clientBuilder.build();
 	}
 
+	/**
+	 * @return A pre-configured JAX-RS target (client w/ base URL) with configured authorization.
+	 */
 	public final WebTarget getTarget() {
 		return this.getTarget(null);
 	}
 
+	/**
+	 * @param authFilter A dynamic authorization filter.
+	 * @return A pre-configured JAX-RS target (client w/ base URL) with the specified authorization.
+	 */
 	public WebTarget getTarget(AuthorizationFilter authFilter) {
 		return this.getClient(authFilter)
 				.target(this.getConfig().getBaseUrl());
 	}
 	
+	/**
+	 * This method retrieves a JAX-RS implementation of the specified API.
+	 * 
+	 * @param apiClass A JAX-RS annotation API class.
+	 * @return An instance of the API class.
+	 */
 	public final <T> T getApi(Class<T> apiClass) {
 		return this.getApi(null, apiClass);
 	}
-	
+
+	/**
+	 * This method retrieves a JAX-RS implementation of the specified API with
+	 * the specified authorization.
+	 * 
+	 * @param authFilter A dynamic authorization filter.
+	 * @param apiClass A JAX-RS annotation API class.
+	 * @return An instance of the API class.
+	 */
 	public abstract <T> T getApi(AuthorizationFilter authFilter, Class<T> apiClass);
 
 }

src/main/java/com/inteligr8/rs/ClientConfiguration.java

@@ -2,48 +2,101 @@ package com.inteligr8.rs;
 
 import java.net.URI;
 
+/**
+ * This interface defines the configurable parameters of the clients; primarily
+ * their default authentication and authorization.
+ * 
+ * @author brian@inteligr8.com
+ */
 public interface ClientConfiguration {
 	
+	/**
+	 * @return The base or root URL of the service.
+	 */
 	String getBaseUrl();
 	
+	/**
+	 * @return The username for BASIC authentication.
+	 */
 	String getBasicAuthUsername();
-	
+
+	/**
+	 * @return The corresponding password for the username in BASIC authentication.
+	 */
 	String getBasicAuthPassword();
 	
-	String getAccessToken();
+	/**
+	 * @return The token for BEARER authorization.
+	 */
+	String getBearerToken();
 	
+	/**
+	 * @return The token URL for OAuth authorization.
+	 */
 	String getOAuthTokenUrl();
 	
+	/**
+	 * @return The client ID provided by the OAuth IdP administrator.
+	 */
 	String getOAuthClientId();
-	
+
+	/**
+	 * @return The corresponding client secret for the client ID provided by the OAuth IdP administrator.
+	 */
 	String getOAuthClientSecret();
 	
+	/**
+	 * @return The authorization code used in the OAuth Authorization Code flow.
+	 */
 	String getOAuthAuthCode();
 	
+	/**
+	 * @return The redirect URL used in the OAuth Authorization Code flow.
+	 */
 	String getOAuthAuthRedirectUri();
 	
+	/**
+	 * @return The username used in the OAuth Password Grant flow.
+	 */
 	String getOAuthUsername();
 	
+	/**
+	 * @return The corresponding password for the username used in the OAuth Password Grant flow.
+	 */
 	String getOAuthPassword();
 
+	/**
+	 * This method creates an authorization filter based on the configuration
+	 * available.  A configuration element is considered to not be available
+	 * when its value is null.  If multiple configurations are specified, the
+	 * filter is selected with the following precedence.
+	 * 
+	 * - Bearer
+	 * - OAuth Authorization Code
+	 * - OAuth Password Grant
+	 * - OAuth Client Credential
+	 * - Basic
+	 * 
+	 * @return An authorization filter; may be null
+	 */
 	default AuthorizationFilter createAuthorizationFilter() {
-		if (this.getAccessToken() != null) {
-			return new AccessTokenRequestFilter(this.getAccessToken());
+		if (this.getBearerToken() != null) {
+			return new BearerTokenAuthorizationFilter(this.getBearerToken());
 		} else if (this.getOAuthTokenUrl() != null) {
 			if (this.getOAuthAuthCode() != null) {
-				return new OAuthAuthorizationCodeRequestFilter(this.getOAuthTokenUrl(),
+				return new OAuthAuthorizationCodeAuthorizationFilter(this.getOAuthTokenUrl(),
 						this.getOAuthClientId(), this.getOAuthClientSecret(),
 						this.getOAuthAuthCode(), URI.create(this.getOAuthAuthRedirectUri()));
 			} else if (this.getOAuthUsername() != null) {
-				return new OAuthPasswordGrantRequestFilter(this.getOAuthTokenUrl(),
+				return new OAuthPasswordGrantAuthorizationFilter(this.getOAuthTokenUrl(),
 						this.getOAuthClientId(), this.getOAuthClientSecret(),
 						this.getOAuthUsername(), this.getOAuthPassword());
 			} else {
-				return new OAuthClientCredentialRequestFilter(this.getOAuthTokenUrl(),
+				return new OAuthClientCredentialAuthorizationFilter(this.getOAuthTokenUrl(),
 						this.getOAuthClientId(), this.getOAuthClientSecret());
 			}
 		} else if (this.getBasicAuthUsername() != null) {
-			return new BasicAuthRequestFilter(this.getBasicAuthUsername(), this.getBasicAuthPassword());
+			return new BasicAuthorizationFilter(this.getBasicAuthUsername(), this.getBasicAuthPassword());
 		} else {
 			return null;
 		}

src/main/java/com/inteligr8/rs/ClientCxfConfiguration.java

@@ -1,7 +1,22 @@
 package com.inteligr8.rs;
 
+/**
+ * This interface defines additional configurations specific to the Apache CXF
+ * JAX-RS library and its nuances.
+ * 
+ * @author brian@inteligr8.com
+ */
 public interface ClientCxfConfiguration extends ClientConfiguration {
 	
+	/**
+	 * Apache CXF uses a global bus configuration where interceptors could
+	 * wreck havoc on your implementation.  This method allows you to
+	 * explicitly by-pass the default bus.
+	 * 
+	 * @see https://cxf.apache.org/docs/bus-configuration.html
+	 * 
+	 * @return true to use the default bus; false otherwise.
+	 */
 	default boolean isDefaultBusEnabled() {
 		return true;
 	}

src/main/java/com/inteligr8/rs/ClientCxfImpl.java

@@ -16,7 +16,10 @@ import org.springframework.beans.factory.InitializingBean;
 import com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider;
 
 /**
- * Configured JAX-RS Client & WebTarget & CXF WebClient for CXF
+ * A class that provides pre-configured JAX-RS Client & WebTarget &
+ * CXF WebClient objects.
+ * 
+ * @author brian@inteligr8.com
  */
 public abstract class ClientCxfImpl extends Client implements InitializingBean {
 	
@@ -27,6 +30,14 @@ public abstract class ClientCxfImpl extends Client implements InitializingBean {
 	
 	@Override
 	public void afterPropertiesSet() {
+		this.register();
+	}
+	
+	/**
+	 * This method registers the Apache CXF library as the default provider for
+	 * the JAX-RS specification.
+	 */
+	public void register() {
 		if (RuntimeDelegate.getInstance() == null) {
 			this.logger.info("Setting JAX-RS runtime delegate to the CXF library");
 			RuntimeDelegate.setInstance(new RuntimeDelegateImpl());
@@ -41,10 +52,17 @@ public abstract class ClientCxfImpl extends Client implements InitializingBean {
 			this.logger.info("API Base URL: " + this.getConfig().getBaseUrl());
 	}
 	
+	/**
+	 * @return A CXF client (not JAX-RS).
+	 */
 	public WebClient getCxfClient() {
 		return this.getCxfClient(null);
 	}
 	
+	/**
+	 * @param authFilter A post-configuration authorization filter.
+	 * @return A CXF client (not JAX-RS).
+	 */
 	public WebClient getCxfClient(AuthorizationFilter authFilter) {
 		List<Object> providersAndFilters = new LinkedList<Object>();
 		providersAndFilters.add(new JacksonJaxbJsonProvider());
@@ -68,7 +86,15 @@ public abstract class ClientCxfImpl extends Client implements InitializingBean {
 		
 		return client;
 	}
-	
+
+	/**
+	 * This method retrieves a JAX-RS implementation of the specified API with
+	 * the specified authorization.
+	 * 
+	 * @param authFilter A dynamic authorization filter.
+	 * @param apiClass A JAX-RS annotation API class.
+	 * @return An instance of the API class.
+	 */
 	@Override
 	public <T> T getApi(AuthorizationFilter authFilter, Class<T> apiClass) {
 		return JAXRSClientFactory.fromClient(this.getCxfClient(authFilter), apiClass);

src/main/java/com/inteligr8/rs/ClientJerseyConfiguration.java

@@ -1,7 +1,19 @@
 package com.inteligr8.rs;
 
+/**
+ * This interface defines additional configurations specific to the Jersey
+ * JAX-RS library and its nuances.
+ * 
+ * @author brian@inteligr8.com
+ */
 public interface ClientJerseyConfiguration extends ClientConfiguration {
 	
+	/**
+	 * Jersey is automatically strict in its adherence to the ReST API
+	 * specifications.  It requires a body to PUT calls by default.
+	 * 
+	 * @return true to require body in PUT calls; false to make it optional
+	 */
 	default boolean isPutBodyRequired() {
 		return true;
 	}

src/main/java/com/inteligr8/rs/ClientJerseyImpl.java

@@ -10,7 +10,10 @@ import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.InitializingBean;
 
 /**
- * Configured JAX-RS Client & WebTarget for Jersey
+ * A class that provides pre-configured JAX-RS Client & WebTarget objects
+ * for Jersey.
+ * 
+ * @author brian@inteligr8.com
  */
 public abstract class ClientJerseyImpl extends Client implements InitializingBean {
 	
@@ -21,6 +24,10 @@ public abstract class ClientJerseyImpl extends Client implements InitializingBea
 	
 	@Override
 	public void afterPropertiesSet() {
+		this.register();
+	}
+	
+	public void register() {
 		if (RuntimeDelegate.getInstance() == null) {
 			this.logger.info("Setting JAX-RS runtime delegate to the Jersey library");
 			RuntimeDelegate.setInstance(new RuntimeDelegateImpl());
@@ -35,6 +42,10 @@ public abstract class ClientJerseyImpl extends Client implements InitializingBea
 			this.logger.info("API Base URL: " + this.getConfig().getBaseUrl());
 	}
 	
+	/**
+	 * @param authFilter A post-configuration authorization filter.
+	 * @return A JAX-RS client.
+	 */
 	@Override
 	public javax.ws.rs.client.Client getClient(AuthorizationFilter authFilter) {
 		javax.ws.rs.client.Client client = super.getClient(authFilter);
@@ -46,7 +57,15 @@ public abstract class ClientJerseyImpl extends Client implements InitializingBea
 		
 		return client;
 	}
-	
+
+	/**
+	 * This method retrieves a JAX-RS implementation of the specified API with
+	 * the specified authorization.
+	 * 
+	 * @param authFilter A dynamic authorization filter.
+	 * @param apiClass A JAX-RS annotation API class.
+	 * @return An instance of the API class.
+	 */
 	@Override
 	public <T> T getApi(AuthorizationFilter authFilter, Class<T> apiClass) {
 		return WebResourceFactory.newResource(apiClass, this.getTarget(authFilter));

src/main/java/com/inteligr8/rs/ForwardingAuthorizationFilter.java

@@ -3,14 +3,32 @@ package com.inteligr8.rs;
 import javax.ws.rs.client.ClientRequestContext;
 import javax.ws.rs.core.HttpHeaders;
 
+/**
+ * This class implements a proxied or forwarded authorization header based
+ * authorization filter.  The authorization header is expected to be acquired
+ * outside of the purview of this library.
+ * 
+ * If you have a bearer token and not the full authorization header, use the
+ * {@link BearerTokenAuthorizationFilter}.
+ *  
+ * @author brian@inteligr8.com
+ */
 public class ForwardingAuthorizationFilter implements AuthorizationFilter {
 	
 	private final String authorizationHeaderValue;
 	
+	/**
+	 * @param authorizationHeaderValue A previously used or formulated 'Authorization' header.
+	 */
 	public ForwardingAuthorizationFilter(String authorizationHeaderValue) {
 		this.authorizationHeaderValue = authorizationHeaderValue;
 	}
-	
+
+	/**
+	 * This method applies the 'Authorization' header to the {@link ClientRequestContext}.
+	 * 
+	 * @param requestContext A request context.
+	 */
 	@Override
 	public void filter(ClientRequestContext requestContext) {
 		requestContext.getHeaders().add(HttpHeaders.AUTHORIZATION, this.authorizationHeaderValue);

src/main/java/com/inteligr8/rs/OAuthAuthorizationCodeAuthorizationFilter.java

@@ -0,0 +1,70 @@
+package com.inteligr8.rs;
+
+import java.net.URI;
+
+import javax.ws.rs.core.Form;
+
+/**
+ * This class implements the OAuth Authorization Code flow as an authorization
+ * filter.
+ * 
+ * @author brian@inteligr8.com
+ */
+public class OAuthAuthorizationCodeAuthorizationFilter extends OAuthAuthorizationFilter {
+	
+	private final String code;
+	private final URI redirectUri;
+	
+	/**
+	 * @param tokenUrl The URL to the OAuth IdP token service.
+	 * @param clientId The ID provided by the OAuth IdP administrator.
+	 * @param code The authorization code acquired from the OAuth IdP from a user outside the purview of this library.
+	 */
+	public OAuthAuthorizationCodeAuthorizationFilter(String tokenUrl, String clientId, String code) {
+		this(tokenUrl, clientId, null, code);
+	}
+
+	/**
+	 * @param tokenUrl The URL to the OAuth IdP token service.
+	 * @param clientId The ID provided by the OAuth IdP administrator.
+	 * @param code The authorization code acquired from the OAuth IdP from a user outside the purview of this library.
+	 * @param redirectUri The URL for the OAuth IdP to redirect after successful authorization.
+	 */
+	public OAuthAuthorizationCodeAuthorizationFilter(String tokenUrl, String clientId, String code, URI redirectUri) {
+		this(tokenUrl, clientId, null, code, redirectUri);
+	}
+
+	/**
+	 * @param tokenUrl The URL to the OAuth IdP token service.
+	 * @param clientId The ID provided by the OAuth IdP administrator.
+	 * @param clientSecret The passcode provided by the OAuth IdP administrator.
+	 * @param code The authorization code acquired from the OAuth IdP from a user outside the purview of this library.
+	 */
+	public OAuthAuthorizationCodeAuthorizationFilter(String tokenUrl, String clientId, String clientSecret, String code) {
+		this(tokenUrl, clientId, clientSecret, code, null);
+	}
+
+	/**
+	 * @param tokenUrl The URL to the OAuth IdP token service.
+	 * @param clientId The ID provided by the OAuth IdP administrator.
+	 * @param clientSecret The passcode provided by the OAuth IdP administrator.
+	 * @param code The authorization code acquired from the OAuth IdP from a user outside the purview of this library.
+	 * @param redirectUri The URL for the OAuth IdP to redirect after successful authorization.
+	 */
+	public OAuthAuthorizationCodeAuthorizationFilter(String tokenUrl, String clientId, String clientSecret, String code, URI redirectUri) {
+		super(tokenUrl, clientId, clientSecret);
+		
+		this.code = code;
+		this.redirectUri = redirectUri;
+	}
+	
+	@Override
+	protected Form createForm() {
+		Form form = new Form().param("grant_type", "authorization_code")
+				.param("code", this.code);
+		if (this.redirectUri != null)
+			form.param("redirect_uri", this.redirectUri.toString());
+		return form;
+	}
+
+}

src/main/java/com/inteligr8/rs/OAuthAuthorizationCodeRequestFilter.java

@@ -1,40 +0,0 @@
-package com.inteligr8.rs;
-
-import java.net.URI;
-
-import javax.ws.rs.core.Form;
-
-public class OAuthAuthorizationCodeRequestFilter extends OAuthRequestFilter {
-	
-	private final String code;
-	private final URI redirectUri;
-	
-	public OAuthAuthorizationCodeRequestFilter(String tokenUrl, String clientId, String code) {
-		this(tokenUrl, clientId, null, code);
-	}
-	
-	public OAuthAuthorizationCodeRequestFilter(String tokenUrl, String clientId, String code, URI redirectUri) {
-		this(tokenUrl, clientId, null, code, redirectUri);
-	}
-	
-	public OAuthAuthorizationCodeRequestFilter(String tokenUrl, String clientId, String clientSecret, String code) {
-		this(tokenUrl, clientId, clientSecret, code, null);
-	}
-	
-	public OAuthAuthorizationCodeRequestFilter(String tokenUrl, String clientId, String clientSecret, String code, URI redirectUri) {
-		super(tokenUrl, clientId, clientSecret);
-		
-		this.code = code;
-		this.redirectUri = redirectUri;
-	}
-	
-	@Override
-	protected Form createForm() {
-		Form form = new Form().param("grant_type", "authorization_code")
-				.param("code", this.code);
-		if (this.redirectUri != null)
-			form.param("redirect_uri", this.redirectUri.toString());
-		return form;
-	}
-
-}

src/main/java/com/inteligr8/rs/OAuthAuthorizationFilter.java

@@ -12,7 +12,12 @@ import javax.ws.rs.core.HttpHeaders;
 
 import com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider;
 
-public abstract class OAuthRequestFilter implements AuthorizationFilter {
+/**
+ * This class is the base for implementations of OAuth authorization flows.
+ *  
+ * @author brian@inteligr8.com
+ */
+public abstract class OAuthAuthorizationFilter implements AuthorizationFilter {
 	
 	private final String tokenUrl;
 	private final String clientId;
@@ -22,21 +27,26 @@ public abstract class OAuthRequestFilter implements AuthorizationFilter {
 	private long expiration;
 	private String refreshToken;
 	
-	public OAuthRequestFilter(String tokenUrl, String clientId) {
+	public OAuthAuthorizationFilter(String tokenUrl, String clientId) {
 		this(tokenUrl, clientId, null);
 	}
 	
-	public OAuthRequestFilter(String tokenUrl, String clientId, String clientSecret) {
+	public OAuthAuthorizationFilter(String tokenUrl, String clientId, String clientSecret) {
 		this(tokenUrl, clientId, clientSecret, null);
 	}
 	
-	public OAuthRequestFilter(String tokenUrl, String clientId, String clientSecret, String scope) {
+	public OAuthAuthorizationFilter(String tokenUrl, String clientId, String clientSecret, String scope) {
 		this.tokenUrl = tokenUrl;
 		this.clientId = clientId;
 		this.clientSecret = clientSecret;
 		this.scope = scope;
 	}
-	
+
+	/**
+	 * This method applies the 'Authorization' header to the {@link ClientRequestContext}.
+	 * 
+	 * @param requestContext A request context.
+	 */
 	@Override
 	public void filter(ClientRequestContext requestContext) {
 		if (this.accessToken == null || System.currentTimeMillis() > this.expiration)
@@ -45,6 +55,10 @@ public abstract class OAuthRequestFilter implements AuthorizationFilter {
 		requestContext.getHeaders().add(HttpHeaders.AUTHORIZATION, "Bearer " + this.accessToken);
 	}
 	
+	/**
+	 * This method manages the acquisition and refreshing of tokens, per the
+	 * standard OAuth process.
+	 */
 	private void requestToken() {
 		Form form;
 		

src/main/java/com/inteligr8/rs/OAuthClientCredentialAuthorizationFilter.java

@@ -0,0 +1,27 @@
+package com.inteligr8.rs;
+
+import javax.ws.rs.core.Form;
+
+/**
+ * This class implements the OAuth Client Credential flow as an authorization
+ * filter.
+ * 
+ * @author brian@inteligr8.com
+ */
+public class OAuthClientCredentialAuthorizationFilter extends OAuthAuthorizationFilter {
+
+	/**
+	 * @param tokenUrl The URL to the OAuth IdP token service.
+	 * @param clientId The ID provided by the OAuth IdP administrator.
+	 * @param clientSecret The passcode provided by the OAuth IdP administrator.
+	 */
+	public OAuthClientCredentialAuthorizationFilter(String tokenUrl, String clientId, String clientSecret) {
+		super(tokenUrl, clientId, clientSecret);
+	}
+	
+	@Override
+	protected Form createForm() {
+		return new Form().param("grant_type", "client_credentials");
+	}
+
+}

src/main/java/com/inteligr8/rs/OAuthClientCredentialRequestFilter.java

@@ -1,16 +0,0 @@
-package com.inteligr8.rs;
-
-import javax.ws.rs.core.Form;
-
-public class OAuthClientCredentialRequestFilter extends OAuthRequestFilter {
-	
-	public OAuthClientCredentialRequestFilter(String tokenUrl, String clientId, String clientSecret) {
-		super(tokenUrl, clientId, clientSecret);
-	}
-	
-	@Override
-	protected Form createForm() {
-		return new Form().param("grant_type", "client_credentials");
-	}
-
-}

src/main/java/com/inteligr8/rs/OAuthPasswordGrantAuthorizationFilter.java

@@ -0,0 +1,46 @@
+package com.inteligr8.rs;
+
+import javax.ws.rs.core.Form;
+
+/**
+ * This class implements the OAuth Password Grant flow as an authorization
+ * filter.
+ * 
+ * @author brian@inteligr8.com
+ */
+public class OAuthPasswordGrantAuthorizationFilter extends OAuthAuthorizationFilter {
+	
+	private final String username;
+	private final String password;
+
+	/**
+	 * @param tokenUrl The URL to the OAuth IdP token service.
+	 * @param clientId The ID provided by the OAuth IdP administrator.
+	 * @param username A username provided by either the OAuth IdP administrator or one of its integrated providers.
+	 * @param password The corresponding password for the username parameter.
+	 */
+	public OAuthPasswordGrantAuthorizationFilter(String tokenUrl, String clientId, String username, String password) {
+		this(tokenUrl, clientId, null, username, password);
+	}
+
+	/**
+	 * @param tokenUrl The URL to the OAuth IdP token service.
+	 * @param clientId The ID provided by the OAuth IdP administrator.
+	 * @param clientSecret The passcode provided by the OAuth IdP administrator.
+	 * @param username A username provided by either the OAuth IdP administrator or one of its integrated providers.
+	 * @param password The corresponding password for the username parameter.
+	 */
+	public OAuthPasswordGrantAuthorizationFilter(String tokenUrl, String clientId, String clientSecret, String username, String password) {
+		super(tokenUrl, clientId, clientSecret);
+		this.username = username;
+		this.password = password;
+	}
+	
+	@Override
+	protected Form createForm() {
+		return new Form().param("grant_type", "password")
+				.param("username", this.username)
+				.param("password", this.password);
+	}
+
+}

src/main/java/com/inteligr8/rs/OAuthPasswordGrantRequestFilter.java

@@ -1,27 +0,0 @@
-package com.inteligr8.rs;
-
-import javax.ws.rs.core.Form;
-
-public class OAuthPasswordGrantRequestFilter extends OAuthRequestFilter {
-	
-	private final String username;
-	private final String password;
-	
-	public OAuthPasswordGrantRequestFilter(String tokenUrl, String clientId, String username, String password) {
-		this(tokenUrl, clientId, null, username, password);
-	}
-	
-	public OAuthPasswordGrantRequestFilter(String tokenUrl, String clientId, String clientSecret, String username, String password) {
-		super(tokenUrl, clientId, clientSecret);
-		this.username = username;
-		this.password = password;
-	}
-	
-	@Override
-	protected Form createForm() {
-		return new Form().param("grant_type", "password")
-				.param("username", this.username)
-				.param("password", this.password);
-	}
-
-}