Unbreak BearerRequester, add javadoc, fix oauth URLs

2 files changed, 37 insertions, 2 deletions

diff --git a/src/mining/AbstractRequester.java b/src/mining/AbstractRequester.java
index a42eb80..bfa2b6d 100644
--- a/src/mining/AbstractRequester.java
+++ b/src/mining/AbstractRequester.java
@@ -1,9 +1,9 @@
 package mining;
 
 import java.io.IOException;
+import java.io.InputStream;
 import java.io.StringWriter;
 import java.net.HttpURLConnection;
-import java.net.MalformedURLException;
 import java.net.URL;
 import java.net.URLConnection;
 import org.apache.commons.io.Charsets;
@@ -18,6 +18,8 @@ import org.json.JSONObject;
  */
 public abstract class AbstractRequester implements Requester {
 
+    private static final String API_URL = "https://api.twitter.com/";
+
     @Override
     public JSONObject getJSON(String resource) throws IOException {
         HttpURLConnection conn = open(buildUrl(resource));
@@ -30,7 +32,12 @@ public abstract class AbstractRequester implements Requester {
     }
 
     protected final URL buildUrl(String resource) throws IOException {
-        String spec = "https://api.twitter.com/1.1/";
+        String spec = API_URL;
+        if (!resource.startsWith("oauth/") && !resource.startsWith("oauth2/")) {
+            // manual inspection shows that at least oauth/ and oauth2/ do not
+            // have a version prefixed.
+            spec += "1.1/";
+        }
         // TODO: detect API version? For example, drop 1.1 for oauth2/token
         spec += resource;
         return new URL(spec);
@@ -38,6 +45,10 @@ public abstract class AbstractRequester implements Requester {
 
     /**
      * Opens a connection to the URL.
+     *
+     * @param url The URL to open a connection to.
+     * @return a connection that can be used for sending requests.
+     * @throws java.io.IOException on failure to open a connection.
      */
     protected final HttpURLConnection open(URL url) throws IOException {
         HttpURLConnection conn = (HttpURLConnection) url.openConnection();
@@ -48,6 +59,11 @@ public abstract class AbstractRequester implements Requester {
 
     /**
      * Reads the response body from a connection (in JSON format).
+     *
+     * @param conn An open connection to which a request was already made.
+     * @return A JSON object as parsed from the response.
+     * @throws java.io.IOException if the response cannot be retrieved or if the
+     * response does not contain well-formed JSON.
      */
     protected final JSONObject getResponseAsJson(URLConnection conn)
             throws IOException {
diff --git a/src/mining/BearerRequester.java b/src/mining/BearerRequester.java
index 94c5314..104dabb 100644
--- a/src/mining/BearerRequester.java
+++ b/src/mining/BearerRequester.java
@@ -18,6 +18,9 @@ import org.json.JSONObject;
  */
 public class BearerRequester extends AbstractRequester {
 
+    /**
+     * A base64-encoded access token that authenticates requests.
+     */
     private final String access_token;
 
     /**
@@ -28,6 +31,14 @@ public class BearerRequester extends AbstractRequester {
         this.access_token = access_token;
     }
 
+    /**
+     * Instantiates an instance, requesting an access token from the provided
+     * consumer key and secret.
+     *
+     * @param consumerKey Key provided by Twitter.
+     * @param consumerSecret Secret provided by Twitter.
+     * @throws IOException if a failure occurred while acquiring a token.
+     */
     public BearerRequester(String consumerKey, String consumerSecret)
             throws IOException {
         String creds = encodeToken(consumerKey, consumerSecret);
@@ -41,6 +52,7 @@ public class BearerRequester extends AbstractRequester {
                 "application/x-www-form-urlencoded; charset=UTF-8");
         conn.setFixedLengthStreamingMode(postData.length());
         // connect and send request
+        conn.setDoOutput(true);
         conn.getOutputStream().write(postData.getBytes(Charsets.UTF_8));
 
         try {
@@ -69,4 +81,11 @@ public class BearerRequester extends AbstractRequester {
         sb.append(consumerSecret);
         return Base64.encodeBase64String(sb.toString().getBytes(Charsets.UTF_8));
     }
+
+    /**
+     * @return the access token that authenticates requests.
+     */
+    public String getAccessToken() {
+        return access_token;
+    }
 }