Skip to content
Browse files

update rdio-simple classes

  • Loading branch information...
1 parent 3cfc217 commit 34d6fa79469b6dce736d372892c3398198aa979a @ianloic ianloic committed Mar 29, 2012
Showing with 73 additions and 26 deletions.
  1. +14 −2 app/com/rdio/simple/Om.java
  2. +56 −24 app/com/rdio/simple/RdioClient.java
  3. +3 −0 app/com/rdio/simple/RdioCoreClient.java
View
16 app/com/rdio/simple/Om.java
@@ -34,7 +34,10 @@
import java.util.HashSet;
import java.util.Random;
-public abstract class Om {
+/**
+ * A straight-forward implementation of OAuth 1.0a message signing.
+ */
+public final class Om {
/**
* Sign an OAuth request.
* @param consumerKey the OAuth consumer key
@@ -204,6 +207,14 @@ private static String HMAC_SHA1(String key, String text) {
base64_map[i] = '/';
}
+ /**
+ * Encode bytes in Base 64.
+ * Based on:
+ * http://www.source-code.biz/base64coder/java/Base64Coder.java.txt
+ *
+ * @param in the bytes to encode
+ * @return Base 64 encoded characters
+ */
public static char[] base64(byte[] in) {
int iLen = in.length;
int oDataLen = (iLen * 4 + 2) / 3; // output length without padding
@@ -229,5 +240,6 @@ private static String HMAC_SHA1(String key, String text) {
return out;
}
-
+ /* no, you can't construct this */
+ private Om() { }
}
View
80 app/com/rdio/simple/RdioClient.java
@@ -23,7 +23,10 @@
import java.io.IOException;
-@SuppressWarnings("UnusedDeclaration")
+/**
+ * The base class for all Rdio clients. It implements the method calling
+ * and auth but does not actually make HTTP requests.
+ */
public abstract class RdioClient {
protected final Consumer consumer;
protected final Token accessToken;
@@ -69,17 +72,17 @@ public Token getAccessToken() {
* @param params the parameters to post
* @param token the token to sign the call with
* @return the response body
- * @throws java.io.IOException in the event of any network errors
- * @throws RdioException
+ * @throws IOException in the event of any network errors
+ * @throws RdioException in the event of an Rdio protocol error
*/
- protected abstract String signedPost(String url, Parameters params, Token token) throws IOException, AuthorizationException, RdioException;
+ protected abstract String signedPost(String url, Parameters params, Token token) throws IOException, RdioException;
/**
* Begin the authentication process. Fetch an OAuth request token associated with the supplied callback.
- * Store it on this Rdio object.
* @param callback the callback URL or "oob" for the PIN flow
* @return the request token and the authorization URL to direct a user to
- * @throws java.io.IOException in the event of any network errors
+ * @throws IOException in the event of any network errors
+ * @throws RdioException in the event of an Rdio protocol error
*/
public AuthState beginAuthentication(String callback) throws IOException, RdioException {
String response = signedPost("http://api.rdio.com/oauth/request_token",
@@ -91,12 +94,13 @@ public AuthState beginAuthentication(String callback) throws IOException, RdioEx
}
/**
- * Complete the authentication process. This Rdio object should have the request token from the beginAuthentication
- * method. When the authentication is complete the access token will be stored on this Rdio object.
- * @param verifier the oauth_verifier from the callback or the PIN displayed to the user
- * @param requestToken the request token returned from the beginAuthentication call
- * @throws java.io.IOException in the event of any network errors
- * @return the access token. pass it to an Rdio constructor to make authenticated calls
+ * Complete the authentication process using the verifier returned from the
+ * Rdio servers and the request token returned from @{link beginAuthentication}.
+ * @param verifier the oauth_verifier from the callback or the PIN displayed to the user
+ * @param requestToken the request token returned from the beginAuthentication call
+ * @throws IOException in the event of any network errors
+ * @throws RdioException in the event of an Rdio protocol error
+ * @return the access token. Pass it to an RdioClient constructor to make authenticated calls
*/
public Token completeAuthentication(String verifier, Token requestToken) throws IOException, RdioException {
String response = signedPost("http://api.rdio.com/oauth/access_token",
@@ -107,10 +111,11 @@ public Token completeAuthentication(String verifier, Token requestToken) throws
/**
* Make and Rdio API call.
- * @param method the name of the method
- * @param parameters the parameters of the method
- * @return the response JSON text
- * @throws java.io.IOException in the event of any network errors
+ * @param method the name of the method
+ * @param parameters the parameters of the method
+ * @return the response JSON text
+ * @throws IOException in the event of any network errors
+ * @throws RdioException in the event of an Rdio protocol error
*/
public String call(String method, Parameters parameters) throws IOException, RdioException {
parameters = (Parameters)parameters.clone();
@@ -120,9 +125,10 @@ public String call(String method, Parameters parameters) throws IOException, Rdi
/**
* Make and Rdio API call with no parameters.
- * @param method the name of the method
- * @return the response JSON text
- * @throws java.io.IOException in the event of any network errors
+ * @param method the name of the method
+ * @return the response JSON text
+ * @throws IOException in the event of any network errors
+ * @throws RdioException in the event of an Rdio protocol error
*/
public String call(String method) throws IOException, RdioException {
return call(method, new Parameters());
@@ -133,9 +139,15 @@ public String call(String method) throws IOException, RdioException {
* An OAuth Consumer key and secret pair.
*/
public static class Consumer {
+ /** The OAuth consumer key */
public final String key;
+ /** The OAuth consumer secret */
public final String secret;
+ /**
+ * @param key the OAuth consumer key
+ * @param secret the OAuth consumer secret
+ */
public Consumer(String key, String secret) {
this.key = key;
this.secret = secret;
@@ -147,9 +159,15 @@ public Consumer(String key, String secret) {
* An OAuth token and token secret pair.
*/
public static final class Token {
+ /** The OAuth token */
public final String token;
+ /** The OAuth token secret */
public final String secret;
-
+
+ /**
+ * @param token the OAuth token
+ * @param secret the OAuth token secret
+ */
public Token(String token, String secret) {
this.token = token;
this.secret = secret;
@@ -161,23 +179,37 @@ public Token(String token, String secret) {
* Intermediate state for OAuth authorization.
*/
public static final class AuthState {
+ /** The OAuth request token.
+ * This will be passed to completeAuthentication.
+ */
public final Token requestToken;
+ /** The OAuth authorization URL.
+ * Redirect the user to this URL to approve the app.
+ */
public final String url;
+ /**
+ * @param requestToken the OAuth request token
+ * @param url the authorization URL
+ */
public AuthState(Token requestToken, String url) {
this.requestToken = requestToken;
this.url = url;
}
}
-
-
+
+ /**
+ * An Rdio protocol error.
+ */
public static class RdioException extends Exception {
public RdioException(String error) {
super(error);
}
private static final long serialVersionUID = -6660585967984993916L;
}
-
-
+
+ /**
+ * Authentication was denied.
+ */
public static class AuthorizationException extends RdioException {
public AuthorizationException(String error) {
super(error);
View
3 app/com/rdio/simple/RdioCoreClient.java
@@ -7,6 +7,9 @@
import java.net.MalformedURLException;
import java.net.URL;
+/**
+ * An RdioClient that uses java.net.HttpURLConnection.
+ */
public class RdioCoreClient extends RdioClient {
public RdioCoreClient(Consumer consumer) {

0 comments on commit 34d6fa7

Please sign in to comment.
Something went wrong with that request. Please try again.