Update document comments.

kumaravel-jayakumar · kumaravel-jayakumar · commit 1aaee59d2fc3 · 2013-06-25T17:41:45.000+05:30
Moved request payload of OAuthTokenCredential as protected method and added a setter for uri part
diff --git a/src/main/java/com/paypal/core/rest/APIContext.java b/src/main/java/com/paypal/core/rest/APIContext.java
@@ -62,10 +62,10 @@ public APIContext(String accessToken) {
 	 *            API service. The token should be of the form 'Bearer xxxx..'.
 	 *            See {@link OAuthTokenCredential} to generate OAuthToken
 	 * @param requestId
-	 *            Unique requestId required for the call. Idempotency id, Calling
-	 *            setMaskRequestId(true) will override the requestId getter to
-	 *            return null, which can be used by the client to forcibly not
-	 *            sent requestId in the API call.
+	 *            Unique requestId required for the call. Idempotency id,
+	 *            Calling setMaskRequestId(true) will override the requestId
+	 *            getter to return null, which can be used by the client (null
+	 *            check) to forcibly not sent requestId in the API call.
 	 */
 	public APIContext(String accessToken, String requestId) {
 		this(accessToken);
diff --git a/src/main/java/com/paypal/core/rest/OAuthTokenCredential.java b/src/main/java/com/paypal/core/rest/OAuthTokenCredential.java
@@ -16,12 +16,29 @@
 import com.paypal.core.credential.ICredential;
 import com.paypal.sdk.util.UserAgentHeader;
 
+/**
+ * OAuthTokenCredential is used for generation of OAuth Token used by PayPal
+ * REST API service. ClientID and ClientSecret are required by the class to
+ * generate OAuth Token, the resulting token is of the form "Bearer xxxxxx". The
+ * class has two constructors, one of it taking an additional configuration map
+ * used for dynamic configuration. When using the constructor with out
+ * configuration map the endpoint is fetched from the configuration that is used
+ * during initialization. See {@link PayPalResource} for configuring the system.
+ * When using a configuration map the class expects an entry by the name
+ * "oauth.EndPoint" or "service.EndPoint" to retrieve the value of the endpoint
+ * for the OAuth Service. If either are not present the configuration should
+ * have a entry by the name "mode" with values sandbox or live wherein the
+ * corresponding endpoints are default to PayPal endpoints.
+ * 
+ * @author kjayakumar
+ * 
+ */
 public final class OAuthTokenCredential implements ICredential {
 
 	/**
 	 * OAuth URI path parameter
 	 */
-	private static final String OAUTH_TOKEN_PATH = "/v1/oauth2/token";
+	private static String OAUTH_TOKEN_PATH = "/v1/oauth2/token";
 
 	/**
 	 * Client ID for OAuth
@@ -43,6 +60,17 @@ public final class OAuthTokenCredential implements ICredential {
 	 */
 	private Map<String, String> configurationMap;
 
+	/**
+	 * Sets the URI path for the OAuth Token service. If not set it defaults to
+	 * "/v1/oauth2/token"
+	 * 
+	 * @param oauthTokenPath
+	 *            the URI part to set
+	 */
+	public static void setOAUTH_TOKEN_PATH(String oauthTokenPath) {
+		OAUTH_TOKEN_PATH = oauthTokenPath;
+	}
+
 	/**
 	 * @param clientID
 	 *            Client ID for the OAuth
@@ -58,10 +86,17 @@ public OAuthTokenCredential(String clientID, String clientSecret) {
 	}
 
 	/**
+	 * Configuration Constructor for dynamic configuration
+	 * 
 	 * @param clientID
 	 *            Client ID for the OAuth
 	 * @param clientSecret
 	 *            Client Secret for OAuth
+	 * @param configurationMap
+	 *            Dynamic configuration map which should have an entry for
+	 *            'oauth.EndPoint' or 'service.EndPoint'. If either are not
+	 *            present then there should be entry for 'mode' with values
+	 *            sandbox/live, wherein PayPals endpoints are used.
 	 */
 	public OAuthTokenCredential(String clientID, String clientSecret,
 			Map<String, String> configurationMap) {
@@ -73,16 +108,13 @@ public OAuthTokenCredential(String clientID, String clientSecret,
 
 	/**
 	 * Computes Access Token by placing a call to OAuth server using ClientID
-	 * and ClientSecret. The token is appended to the token type.
+	 * and ClientSecret. The token is appended to the token type (Bearer).
 	 * 
 	 * @return the accessToken
 	 * @throws PayPalRESTException
 	 */
 	public String getAccessToken() throws PayPalRESTException {
 		if (accessToken == null) {
-			// Write Logic for passing in Detail to Identity Api Serv and
-			// computing the token
-			// Set the Value inside the accessToken and result
 			accessToken = generateAccessToken();
 		}
 		return accessToken;
@@ -125,12 +157,13 @@ private String generateOAuthToken(String base64ClientID)
 			httpConfiguration = getOAuthHttpConfiguration();
 			connection.createAndconfigureHttpConnection(httpConfiguration);
 			Map<String, String> headers = new HashMap<String, String>();
-			headers.put(Constants.AUTHORIZATION_HEADER, "Basic " + base64ClientID);
+			headers.put(Constants.AUTHORIZATION_HEADER, "Basic "
+					+ base64ClientID);
 			headers.put(Constants.HTTP_ACCEPT_HEADER, "*/*");
 			UserAgentHeader userAgentHeader = new UserAgentHeader(
 					PayPalResource.SDK_ID, PayPalResource.SDK_VERSION);
 			headers.putAll(userAgentHeader.getHeader());
-			String postRequest = "grant_type=client_credentials";
+			String postRequest = getRequestPayload();
 			String jsonResponse = connection.execute("", postRequest, headers);
 			JsonParser parser = new JsonParser();
 			JsonElement jsonElement = parser.parse(jsonResponse);
@@ -145,16 +178,25 @@ private String generateOAuthToken(String base64ClientID)
 		return generatedToken;
 	}
 
+	/**
+	 * Returns the request payload for OAuth Service. Override this method to
+	 * alter the payload
+	 * 
+	 * @return Payload as String
+	 */
+	protected String getRequestPayload() {
+		return "grant_type=client_credentials";
+	}
+
 	/*
 	 * Get HttpConfiguration object for OAuth server
 	 */
 	private HttpConfiguration getOAuthHttpConfiguration() {
 		HttpConfiguration httpConfiguration = new HttpConfiguration();
 		httpConfiguration
 				.setHttpMethod(Constants.HTTP_CONFIG_DEFAULT_HTTP_METHOD);
-		String endPointUrl = (configurationMap.get(Constants.OAUTH_ENDPOINT) != null
-				&& configurationMap.get(Constants.OAUTH_ENDPOINT).trim()
-						.length() >= 0) ? configurationMap
+		String endPointUrl = (configurationMap.get(Constants.OAUTH_ENDPOINT) != null && configurationMap
+				.get(Constants.OAUTH_ENDPOINT).trim().length() >= 0) ? configurationMap
 				.get(Constants.OAUTH_ENDPOINT) : configurationMap
 				.get(Constants.ENDPOINT);
 		if (endPointUrl == null || endPointUrl.trim().length() <= 0) {
diff --git a/src/main/java/com/paypal/core/rest/PayPalRESTException.java b/src/main/java/com/paypal/core/rest/PayPalRESTException.java
@@ -5,6 +5,11 @@
  */
 public class PayPalRESTException extends Exception {
 
+	/**
+	 * Serial Version ID
+	 */
+	private static final long serialVersionUID = 1L;
+
 	public PayPalRESTException(String message) {
 		super(message);
 	}
diff --git a/src/main/java/com/paypal/core/rest/RESTUtil.java b/src/main/java/com/paypal/core/rest/RESTUtil.java
@@ -9,7 +9,11 @@
 import com.paypal.sdk.openidconnect.CreateFromRefreshTokenParameters;
 import com.paypal.sdk.openidconnect.UserinfoParameters;
 
-
+/**
+ * <code>RESTUtil</code> acts as utility class used by REST API system
+ * @author kjayakumar
+ *
+ */
 public final class RESTUtil {
 	
 	private RESTUtil() {}
