Double-Checking and documenting: Expand, Info

CHANGELOG

@@ -1,3 +1,8 @@
+[?.?.?]
+
+* IMPROVEMENT: Expand Refactoring and Javadoc (partially copied directly from bitly)
+* IMPROVEMENT: Info   Refactoring and Javadoc (partially copied directly from bitly)
+
 [0.5.0]
 
 more or less feature complete. most metrics are there with an expanded variant, the rolledup one needs a closer look and once I've figured out how this stuff actually works I'll add it too but for the moment this is a pretty usable state right now.

LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright (c) Patrick Huber / stackmagic@gmail.com
+   Copyright (c) Patrick Huber (gmail: stackmagic)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

TODO

@@ -0,0 +1,3 @@
+* Expand: Eliminate duplicate parameters
+* Expand: Throw exception when exceeding max of 15 hash/shortUrls
+* Expand: Throw exception when not at least 1 hash/shortUrls

src/main/java/net/swisstech/bitly/builder/Request.java

@@ -32,6 +32,13 @@
 
 import com.google.gson.Gson;
 
+/**
+ * Base Request Builder and logic to make the actual call, add query parameters etc.
+ * 
+ * @author Patrick Huber (gmail: stackmagic)
+ *
+ * @param <T> Type of the Response
+ */
 public abstract class Request<T> {
 
 	private final String accessToken;
@@ -55,6 +62,7 @@ public List<QueryParameter> getQueryParameters() {
 	 * to return an explicit type here, no T parameters or anything because that
 	 * won't work and then GSON will serialize the responsee's data as a
 	 * StringMap.
+	 * 
 	 * @return Type for GSON deserializer
 	 */
 	protected abstract Type getTypeForGson();

src/main/java/net/swisstech/bitly/builder/v3/ExpandRequest.java

@@ -20,7 +20,7 @@
 
 import net.swisstech.bitly.builder.Request;
 import net.swisstech.bitly.model.Response;
-import net.swisstech.bitly.model.v3.Expand;
+import net.swisstech.bitly.model.v3.ExpandResponse;
 
 import com.google.gson.reflect.TypeToken;
 
@@ -31,8 +31,12 @@
  * 
  * @author Patrick Huber (gmail: stackmagic)
  */
-public class ExpandRequest extends Request<Expand> {
+public class ExpandRequest extends Request<ExpandResponse> {
 
+	/**
+	 * Create a new ExpandRequest Builder
+	 * @param accessToken the access token to access the bitly api
+	 */
 	public ExpandRequest(String accessToken) {
 		super(accessToken);
 	}
@@ -44,41 +48,71 @@ public String getEndpoint() {
 
 	@Override
 	protected Type getTypeForGson() {
-		return new TypeToken<Response<Expand>>() {
+		return new TypeToken<Response<ExpandResponse>>() {
 		}.getType();
 	}
+	/**
+	 * Add a hash
+	 * @param hash refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name )
+	 * @return this builder
+	 */
 
 	public ExpandRequest addHash(String hash) {
 		addQueryParameter("hash", hash);
 		return this;
 	}
 
+	/**
+	 * Add hashes
+	 * @param hashes refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name )
+	 * @return this builder
+	 */
 	public ExpandRequest addHashes(String... hashes) {
 		for (String hash : hashes) {
 			addHash(hash);
 		}
 		return this;
 	}
 
+	/**
+	 * Add hashes
+	 * @param hashes refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name )
+	 * @return this builder
+	 */
 	public ExpandRequest addHashes(Collection<String> hashes) {
 		for (String hash : hashes) {
 			addHash(hash);
 		}
 		return this;
 	}
 
+	/**
+	 * Add shortUrl
+	 * @param shortUrl refers to one or more bitly links e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT
+	 * @return this builder
+	 */
 	public ExpandRequest addShortUrl(String shortUrl) {
 		addQueryParameter("shortUrl", shortUrl);
 		return this;
 	}
 
+	/**
+	 * Add shortUrls
+	 * @param shortUrls refers to one or more bitly links e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT
+	 * @return this builder
+	 */
 	public ExpandRequest addShortUrls(String... shortUrls) {
 		for (String shortUrl : shortUrls) {
 			addShortUrl(shortUrl);
 		}
 		return this;
 	}
 
+	/**
+	 * Add shortUrls
+	 * @param shortUrls refers to one or more bitly links e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT
+	 * @return this builder
+	 */
 	public ExpandRequest addShortUrls(Collection<String> shortUrls) {
 		for (String shortUrl : shortUrls) {
 			addShortUrl(shortUrl);

src/main/java/net/swisstech/bitly/builder/v3/InfoRequest.java

@@ -20,7 +20,7 @@
 
 import net.swisstech.bitly.builder.Request;
 import net.swisstech.bitly.model.Response;
-import net.swisstech.bitly.model.v3.Info;
+import net.swisstech.bitly.model.v3.InfoResponse;
 
 import com.google.gson.reflect.TypeToken;
 
@@ -31,8 +31,12 @@
  * 
  * @author Patrick Huber (gmail: stackmagic)
  */
-public class InfoRequest extends Request<Info> {
+public class InfoRequest extends Request<InfoResponse> {
 
+	/**
+	 * Create new InfoRequest Builder
+	 * @param accessToken the access token to access the bitly api
+	 */
 	public InfoRequest(String accessToken) {
 		super(accessToken);
 	}
@@ -44,46 +48,81 @@ public String getEndpoint() {
 
 	@Override
 	protected Type getTypeForGson() {
-		return new TypeToken<Response<Info>>() {
+		return new TypeToken<Response<InfoResponse>>() {
 		}.getType();
 	}
 
-	public InfoRequest setExpandUser(boolean expand) {
-		addQueryParameter("expand_user", expand);
+	/**
+	 * Set wether or not user info should be included in the response
+	 * @param expandUser include extra user info in response
+	 * @return this builder
+	 */
+	public InfoRequest setExpandUser(boolean expandUser) {
+		addQueryParameter("expand_user", expandUser);
 		return this;
 	}
 
+	/**
+	 * Add a hash
+	 * @param hash refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name )
+	 * @return this builder
+	 */
 	public InfoRequest addHash(String hash) {
 		addQueryParameter("hash", hash);
 		return this;
 	}
 
+	/**
+	 * Add hashes
+	 * @param hashes refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name )
+	 * @return this builder
+	 */
 	public InfoRequest addHashes(String... hashes) {
 		for (String hash : hashes) {
 			addHash(hash);
 		}
 		return this;
 	}
 
+	/**
+	 * Add hashes
+	 * @param hashes refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name )
+	 * @return this builder
+	 */
 	public InfoRequest addHashes(Collection<String> hashes) {
 		for (String hash : hashes) {
 			addHash(hash);
 		}
 		return this;
 	}
 
+	/**
+	 * Add shortUrl
+	 * @param shortUrl refers to one or more bitly links e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT
+	 * @return this builder
+	 */
 	public InfoRequest addShortUrl(String shortUrl) {
 		addQueryParameter("shortUrl", shortUrl);
 		return this;
 	}
 
+	/**
+	 * Add shortUrls
+	 * @param shortUrls refers to one or more bitly links e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT
+	 * @return this builder
+	 */
 	public InfoRequest addShortUrls(String... shortUrls) {
 		for (String shortUrl : shortUrls) {
 			addShortUrl(shortUrl);
 		}
 		return this;
 	}
 
+	/**
+	 * Add shortUrls
+	 * @param shortUrls refers to one or more bitly links e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT
+	 * @return this builder
+	 */
 	public InfoRequest addShortUrls(Collection<String> shortUrls) {
 		for (String shortUrl : shortUrls) {
 			addShortUrl(shortUrl);

src/main/java/net/swisstech/bitly/model/MetricsResponse.java

@@ -25,5 +25,4 @@ public abstract class MetricsResponse extends ToStringSupport {
 	public String unit;
 
 	public long days;
-
 }

src/main/java/net/swisstech/bitly/model/Response.java

@@ -15,12 +15,36 @@
  */
 package net.swisstech.bitly.model;
 
+/**
+ * <p>
+ * Base response from the API. If the <code>status_code</code> or <code>status_txt</code> contain an error, it's very likely, that the
+ * <code>data</code> field will be null or may contain garbage.
+ * </p>
+ * 
+ * <p>
+ * For more information on the base formats please see the <a href="http://dev.bitly.com/formats.html">bit.ly documentation on formats<O/a>.
+ * </p>
+ * 
+ * @author Patrick Huber (gmail: stackmagic)
+ * 
+ * @param <T> Type of the Response
+ */
 public class Response<T> extends ToStringSupport {
 
+	/**
+	 * The status_code is 200 for a successful request, 403 when rate limited, 503 for temporary unavailability, 404 to indicate not-found responses,
+	 * and 500 for all other invalid requests or responses
+	 */
 	public int status_code;
 
+	/**
+	 * status_txt will be a value that describes the nature of any error encountered. Common values are RATE_LIMIT_EXCEEDED, MISSING_ARG_%s to denote
+	 * a missing URL parameter, and INVALID_%s to denote an invalid value in a request parameter (where %s is substituted with the name of the request
+	 * parameter)
+	 */
 	public String status_txt;
 
+	/** the actual response data */
 	public T data;
 
 }

src/main/java/net/swisstech/bitly/model/v3/Expand.java → src/main/java/net/swisstech/bitly/model/v3/ExpandResponse.java

@@ -19,22 +19,37 @@
 
 import net.swisstech.bitly.model.ToStringSupport;
 
-public class Expand extends ToStringSupport {
+/**
+ * <p>
+ * Please see the bit.ly documentation for the <a href="http://dev.bitly.com/links.html#v3_expand">/v3/expand</a> request.
+ * </p>
+ * 
+ * @author Patrick Huber (gmail: stackmagic)
+ */
+public class ExpandResponse extends ToStringSupport {
 
-	public List<Element> expand;
+	/** list of the expanded shortUrls or hashes */
+	public List<Expand> expand;
 
-	public static class Element extends ToStringSupport {
+	/** an individual expanded shortUrl or hash */
+	public static class Expand extends ToStringSupport {
 
+		/** an echo back of the shortUrl request parameter */
 		public String short_url;
 
+		/** an echo back of the hash request parameter */
 		public String hash;
 
+		/** the corresponding bitly user identifier */
 		public String user_hash;
 
+		/** the corresponding bitly aggregate identifier */
 		public String global_hash;
 
+		/** indicates there was an error retrieving data for a given shortUrl or hash. An example error is "NOT_FOUND" */
 		public String error;
 
+		/** the URL that the requested short_url or hash points to */
 		public String long_url;
 	}
 }