updated javadoc

Author: Synapticloop

src/main/java/synapticloop/b2/B2ApiClient.java

@@ -67,8 +67,21 @@ public class B2ApiClient {
 
 	private final CloseableHttpClient client;
 
+	/**
+	 * Create a B2ApiClient and authenticate
+	 * 
+	 * @param accountId The account id
+	 * @param applicationKey the application key
+	 * @throws B2ApiException if there was an error authenticating the account
+	 */
+	public B2ApiClient(String accountId, String applicationKey) throws B2ApiException {
+		this();
+		this.b2AuthorizeAccountResponse = authenticate(accountId, applicationKey);
+	}
+
 	/**
 	 * Must authenticate first before API actions are available. Using default HTTP client configuration
+	 * 
 	 * @see #authenticate(String, String)
 	 */
 	public B2ApiClient() {
@@ -330,7 +343,7 @@ public B2FileResponse uploadFile(String bucketId, String fileName, File file, St
 	 */
 
 	public B2FileResponse uploadFile(String bucketId, String fileName, File file, Map<String, String> fileInfo) throws B2ApiException {
-		B2GetUploadUrlResponse b2GetUploadUrlResponse = new B2GetUploadUrlRequest(client, b2AuthorizeAccountResponse, bucketId, fileInfo).getResponse();
+		B2GetUploadUrlResponse b2GetUploadUrlResponse = new B2GetUploadUrlRequest(client, b2AuthorizeAccountResponse, bucketId).getResponse();
 		return new B2UploadFileRequest(client, b2AuthorizeAccountResponse, b2GetUploadUrlResponse, fileName, file, fileInfo).getResponse();
 	}
 

src/main/java/synapticloop/b2/io/HttpMethodReleaseInputStream.java

@@ -31,7 +31,10 @@ public class HttpMethodReleaseInputStream extends CountingInputStream {
 	private HttpResponse response;
 
 	/**
+	 * Create a HTTP method release input Stream
+	 * 
 	 * @param response The HTTP response to read from
+	 * 
 	 * @throws IOException If there is a problem reading from the response
 	 * @throws NullPointerException If the response has no message entity
 	 */
@@ -54,8 +57,7 @@ public void close() throws IOException {
 			if(read == response.getEntity().getContentLength()) {
 				// Fully consumed
 				super.close();
-			}
-			else {
+			} else {
 				if(LOGGER.isLoggable(Level.WARNING)) {
 					LOGGER.warning(String.format("Abort connection for response '{}'", response));
 				}
@@ -66,8 +68,7 @@ public void close() throws IOException {
 				// The response proxy will force close the connection.
 				((CloseableHttpResponse) response).close();
 			}
-		}
-		else {
+		} else {
 			// Consume and close
 			super.close();
 		}

src/main/java/synapticloop/b2/request/B2AuthorizeAccountRequest.java

@@ -32,6 +32,14 @@
  * used for account-level operations, and a URL that should be used as the base 
  * URL for subsequent API calls.</p>
  * 
+ * An HTTP basic auth value constructed as follows:
+ * <ul>
+ *   <li>The B2 account id and B2 application key for the account are combined 
+ *   into a string in the format "accountId:applicationKey".</li>
+ *   <li>The combined string is Base64 encoded.</li>
+ *   <li>"Basic " is put before the encoded string.</li>
+ * </ul>
+ * 
  * This is the interaction class for the <strong>b2_authorize_account</strong> api 
  * calls, this was generated from the backblaze api documentation - which can be 
  * found here:

src/main/java/synapticloop/b2/request/B2CancelLargeFileRequest.java

@@ -14,8 +14,7 @@
  * 
  * <p>This will return an error if there is no active upload with the given file ID.</p>
  * 
- * 
- *This is the interaction class for the <strong>b2_authorize_account</strong> api 
+ * This is the interaction class for the <strong>b2_cancel_large_file</strong> api 
  * calls, this was generated from the backblaze api documentation - which can be 
  * found here:
  * 
@@ -28,12 +27,28 @@
 public class B2CancelLargeFileRequest extends BaseB2Request {
 	private static final String B2_CANCEL_LARGE_FILE = BASE_API + "b2_cancel_large_file";
 
+	/**
+	 * Create a cancel large file request
+	 * 
+	 * @param client The HTTP client to use
+	 * @param b2AuthorizeAccountResponse the authorize account response
+	 * @param fileId The ID returned by B2StartLargeFileRequest.
+	 * 
+	 * {@link B2StartLargeFileRequest}
+	 */
 	protected B2CancelLargeFileRequest(CloseableHttpClient client, B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String fileId) {
 		super(client, b2AuthorizeAccountResponse, b2AuthorizeAccountResponse.getApiUrl() + B2_CANCEL_LARGE_FILE);
 
 		requestBodyData.put(B2RequestProperties.KEY_FILE_ID, fileId);
 	}
 
+	/**
+	 * Get the file response
+	 * 
+	 * @return the B2 File response
+	 * 
+	 * @throws B2ApiException if there was an error retrieving the response
+	 */
 	public B2FileResponse getResponse() throws B2ApiException {
 		try {
 			return(new B2FileResponse(EntityUtils.toString(executePost().getEntity())));

src/main/java/synapticloop/b2/request/B2DeleteBucketRequest.java

@@ -44,7 +44,7 @@ public class B2DeleteBucketRequest extends BaseB2Request {
 	 *
 	 * @param client Shared HTTP client instance
 	 * @param b2AuthorizeAccountResponse the authorize account response
-	 * @param bucketId the id of the bucket to delete
+	 * @param bucketId The id of the bucket to delete
 	 */
 	public B2DeleteBucketRequest(CloseableHttpClient client, B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String bucketId) {
 

src/main/java/synapticloop/b2/request/B2DeleteFileVersionRequest.java

@@ -32,7 +32,7 @@
  * <p>If the version you delete is the latest version, and there are older 
  * versions, then the most recent older version will become the current 
  * version, and be the one that you'll get when downloading by name. See 
- * the File Versions page for more details.</p>
+ * the <a href="https://www.backblaze.com/b2/docs/file_versions.html">File Versions</a> page for more details.</p>
  * 
  * 
  * This is the interaction class for the <strong>b2_delete_file_version</strong> api calls, this was
@@ -50,9 +50,9 @@ public class B2DeleteFileVersionRequest extends BaseB2Request {
 	 *
 	 * @param client Shared HTTP client instance
 	 * @param b2AuthorizeAccountResponse the authorize account response
-	 * @param fileName the name of the file to delete
+	 * @param fileName the name (and path) of the file to delete
 	 * @param fileId The ID of the file, as returned by {@link B2UploadFileRequest},
-	 *    {@link B2ListFileNamesRequest}, or {@link B2ListFileVersionsRequest}..
+	 *    {@link B2ListFileNamesRequest}, or {@link B2ListFileVersionsRequest}.
 	 */
 	public B2DeleteFileVersionRequest(CloseableHttpClient client, B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String fileName, String fileId) {
 
@@ -63,7 +63,7 @@ public B2DeleteFileVersionRequest(CloseableHttpClient client, B2AuthorizeAccount
 	}
 
 	/**
-	 * Return the http response for the call
+	 * Return the response for the call
 	 * 
 	 * @return the delete file version response
 	 * 

src/main/java/synapticloop/b2/request/B2DownloadFileByIdRequest.java

@@ -28,6 +28,25 @@
  * 
  * <p>The response contains the following headers, which contain the same information they did when the file was uploaded:</p>
  * 
+ * <ul>
+ *   <li>Content-Length</li>
+ *   <li>Content-Type</li>
+ *   <li>X-Bz-File-Id</li>
+ *   <li>X-Bz-File-Name</li>
+ *   <li>X-Bz-Content-Sha1</li>
+ *   <li>X-Bz-Info-*</li>
+ * </ul>
+ * 
+ * <p>HEAD requests are also supported, and work just like a GET, except that the 
+ * body of the response is not included. All of the same headers, including 
+ * Content-Length are returned. See the B2HeadFileByIdRequest</p>
+ * 
+ * <p>If the bucket containing the file is set to require authorization, then you 
+ * must supply the bucket's auth token in the Authorzation header.</p>
+ * 
+ * <p>Because errors can happen in network transmission, you should check the 
+ * SHA1 of the data you receive against the SHA1 returned in the 
+ * X-Bz-Content-Sha1 header.</p>
  * 
  * This is the interaction class for the <strong>b2_download_file_by_id</strong> api calls, this was
  * generated from the backblaze api documentation - which can be found here:

src/main/java/synapticloop/b2/request/B2DownloadFileByNameRequest.java

@@ -39,12 +39,40 @@
  */
 public class B2DownloadFileByNameRequest extends BaseB2Request {
 
+	/**
+	 * Create a download file by name request
+	 * 
+	 * @param client The http client to use
+	 * @param b2AuthorizeAccountResponse the authorize account response
+	 * @param bucketName the name of the bucket
+	 * @param fileName the name and path of the file
+	 */
 	public B2DownloadFileByNameRequest(CloseableHttpClient client, B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String bucketName, String fileName) {
 		super(client, 
 				b2AuthorizeAccountResponse, 
 				b2AuthorizeAccountResponse.getDownloadUrl() + "/file/" + Helper.urlEncode(bucketName) + "/" + Helper.urlEncodeFileName(fileName));
 	}
 
+	/**
+	 * Create a download file by name request with a specified range
+	 * 
+	 * A standard byte-range request, which will return just part of the stored file.
+	 * 
+	 * The value "bytes=0-99" selects bytes 0 through 99 (inclusive) of the file, 
+	 * so it will return the first 100 bytes. Valid byte ranges will cause the 
+	 * response to contain a Content-Range header that specifies which bytes 
+	 * are returned. Invalid byte ranges will just return the whole file.
+	 * 
+	 * Note that the SHA1 checksum returned is still the checksum for the entire 
+	 * file, so it cannot be used on the byte range.
+	 * 
+	 * @param client The http client to use
+	 * @param b2AuthorizeAccountResponse the authorize account response
+	 * @param bucketName the name of the bucket
+	 * @param fileName the name and path of the file
+	 * @param rangeStart the range start of the partial file contents
+	 * @param rangeEnd the range end of the partial file contents
+	 */
 	public B2DownloadFileByNameRequest(CloseableHttpClient client, B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String bucketName, String fileName, long rangeStart, long rangeEnd) {
 		this(client, b2AuthorizeAccountResponse, bucketName, fileName);
 		requestHeaders.put(HttpHeaders.RANGE, "bytes=" + rangeStart + "-" + rangeEnd);

src/main/java/synapticloop/b2/request/B2GetFileInfoRequest.java

@@ -43,7 +43,11 @@ public class B2GetFileInfoRequest extends BaseB2Request {
 	 *
 	 * @param client Shared HTTP client instance
 	 * @param b2AuthorizeAccountResponse the authorize account response
-	 * @param fileId the id for the file
+	 * @param fileId The ID of the file, as returned by b2_upload_file, b2_list_file_names, or b2_list_file_versions.
+	 * 
+	 * {@link B2UploadFileRequest}
+	 * {@link B2ListFileNamesRequest}
+	 * {@link B2ListFileVersionsRequest}
 	 */
 	public B2GetFileInfoRequest(CloseableHttpClient client, B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String fileId) {
 		super(client, b2AuthorizeAccountResponse, b2AuthorizeAccountResponse.getApiUrl() + B2_GET_FILE_INFO);

src/main/java/synapticloop/b2/request/B2GetUploadUrlRequest.java

@@ -17,7 +17,6 @@
  */
 
 import java.io.IOException;
-import java.util.Map;
 
 import org.apache.http.impl.client.CloseableHttpClient;
 import org.apache.http.util.EntityUtils;
@@ -42,18 +41,19 @@
 public class B2GetUploadUrlRequest extends BaseB2Request {
 	private static final String B2_GET_UPLOAD_URL = BASE_API_VERSION + "b2_get_upload_url";
 
+	/**
+	 * Instantiate a get upload URL request
+	 * 
+	 * @param client the HTTP client to use
+	 * @param b2AuthorizeAccountResponse the authorize account response
+	 * @param bucketId The ID of the bucket that you want to upload to.
+	 */
 	public B2GetUploadUrlRequest(CloseableHttpClient client, B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String bucketId) {
 		super(client, b2AuthorizeAccountResponse, b2AuthorizeAccountResponse.getApiUrl() + B2_GET_UPLOAD_URL);
 
 		requestBodyData.put(B2RequestProperties.KEY_BUCKET_ID, bucketId);
 	}
 
-	public B2GetUploadUrlRequest(CloseableHttpClient client, B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String bucketId, Map<String, String> fileInfo) {
-		super(client, b2AuthorizeAccountResponse, b2AuthorizeAccountResponse.getApiUrl() + B2_GET_UPLOAD_URL);
-
-		requestBodyData.put(B2RequestProperties.KEY_BUCKET_ID, bucketId);
-	}
-
 	/**
 	 * Return the upload url response 
 	 *