updated documentation, minor logging changes

Author: Synapticloop

README.md

@@ -1,3 +1,5 @@
+<img src="https://travis-ci.org/synapticloop/backblaze-b2-java-api.svg?branch=master" />
+
 A Java API for the truly excellent backblaze B2 storage
 
 # Usage
@@ -67,7 +69,7 @@ And now for the dependency
     <dependency>
       <groupId>synapticloop</groupId>
       <artifactId>backblaze-b2-java-api</artifactId>
-      <version>v1.0.0</version>
+      <version>v1.0.2</version>
       <type>jar</type>
     </dependency>
 
@@ -90,15 +92,15 @@ Repository
 
 and then include the dependency:
 
-    runtime(group: 'synapticloop', name: 'backblaze-b2-java-api', version: 'v1.0.0', ext: 'jar')
+    runtime(group: 'synapticloop', name: 'backblaze-b2-java-api', version: 'v1.0.2', ext: 'jar')
 
-    compile(group: 'synapticloop', name: 'backblaze-b2-java-api', version: 'v1.0.0', ext: 'jar')
+    compile(group: 'synapticloop', name: 'backblaze-b2-java-api', version: 'v1.0.2', ext: 'jar')
 
 or 
 
-    runtime 'synapticloop:backblaze-b2-java-api:v1.0.0'
+    runtime 'synapticloop:backblaze-b2-java-api:v1.0.2'
 
-    compile 'synapticloop:backblaze-b2-java-api:v1.0.0'
+    compile 'synapticloop:backblaze-b2-java-api:v1.0.2'
 
 ## Other
 
@@ -115,7 +117,15 @@ which can be found by searching here: [http://mvnrepository.com/](http://mvnrepo
 
 # Running the Tests
 
-`gradled --info test`
+`gradlew build`
+
+this will output the artefacts into the `build/libs/` directory.
+
+Note that this will also run all of the tests (see notes below)
+
+# Running the Tests
+
+`gradlew --info test`
 
 Which will also print out the logging
 
@@ -132,4 +142,5 @@ export B2_ACCOUNT_ID="your-account-id"
 export B2_APPLICATION_KEY="your-application-key"
 ```
 
-**WARNING:** These tests make API calls against your account which contribute to your call limits, which may lead to a cost.
+**WARNING:** These tests make API calls against your account which contribute to your call limits, which may lead to a cost.
+

build.gradle

@@ -11,7 +11,7 @@ group = 'synapticloop'
 archivesBaseName = 'backblaze-b2-java-api'
 description = """An api for backblaze b2 storage in java"""
 
-version = 'v1.0.1'
+version = 'v1.0.2'
 
 description = """backblaze-b2-java-api"""
 

src/main/java/synapticloop/b2/Action.java

@@ -1,7 +1,7 @@
 package synapticloop.b2;
 
 /**
- * The action for an associated file.
+ * The action for an associated file, either 'hide' or 'upload'
  * 
  * @author synapticloop
  */

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

@@ -44,7 +44,7 @@ public class B2ApiClient {
 	private String accountId = null;
 	private String applicationKey = null;
 
-	B2AuthorizeAccountResponse b2AuthorizeAccountResponse = null;
+	private B2AuthorizeAccountResponse b2AuthorizeAccountResponse = null;
 
 	/**
 	 * Instantiate a new B2ApiClient object
@@ -225,12 +225,22 @@ public B2UploadFileRequest uploadFile(String bucketId, String fileName, File fil
 		return(new B2UploadFileRequest(getB2AuthorizeAccountResponse(), b2GetUploadUrlResponse, fileName, file));
 	}
 
+	/**
+	 * Delete a version of a file
+	 * 
+	 * @param fileName The name of the file to delete
+	 * @param fileId The version of the file to delete
+	 * 
+	 * @return the deleted file response
+	 * 
+	 * @throws B2ApiException if there was an error deleting the file
+	 */
 	public B2DeleteFileVersionResponse deleteFileVersion(String fileName, String fileId) throws B2ApiException {
 		return(new B2DeleteFileVersionRequest(getB2AuthorizeAccountResponse(), fileName, fileId).getResponse());
 	}
 
 	/**
-	 * Update a busket to be a specified type
+	 * Update a bucket to be a specified type
 	 * 
 	 * @param bucketId the id of the bucket to set
 	 * @param bucketType the type of the bucket
@@ -274,14 +284,46 @@ public B2ListFilesResponse listFileNames(String bucketId, String startFileName,
 		return(new B2ListFileNamesRequest(getB2AuthorizeAccountResponse(), bucketId, startFileName, maxFileCount).getResponse());
 	}
 
+	/**
+	 * List the files and versions for a specific bucket
+	 * 
+	 * @param bucketId the id of the bucket to list
+	 * 
+	 * @return the list file response
+	 * 
+	 * @throws B2ApiException if there was an error with the call
+	 */
 	public B2ListFilesResponse listFileVersions(String bucketId) throws B2ApiException {
 		return(new B2ListFileVersionsRequest(getB2AuthorizeAccountResponse(), bucketId).getResponse());
 	}
 
+	/**
+	 * List the file versions in a bucket starting at a specific file name
+	 * 
+	 * @param bucketId the id of the bucket
+	 * @param startFileName the file name to start with
+	 * 
+	 * @return the list file response
+	 * 
+	 * @throws B2ApiException if there was an error with the call
+	 */
 	public B2ListFilesResponse listFileVersions(String bucketId, String startFileName) throws B2ApiException {
 		return(new B2ListFileVersionsRequest(getB2AuthorizeAccountResponse(), bucketId, startFileName, null, null).getResponse());
 	}
 
+	/**
+	 * List the file versions in a bucket starting at a specific file name and file id
+	 * 
+	 * @param bucketId the id of the bucket
+	 * @param startFileName the file name to start with
+	 * @param startFileId the id of the file to start with
+	 * @param maxFileCount the maximum number of files to return (must be less 
+	 *     than or equal to 1000, else an error is thrown)
+	 * 
+	 * @return the list files response
+	 * 
+	 * @throws B2ApiException if there was an error with the call
+	 */
 	public B2ListFilesResponse listFileVersions(String bucketId, String startFileName, String startFileId, Integer maxFileCount) throws B2ApiException {
 		return(new B2ListFileVersionsRequest(getB2AuthorizeAccountResponse(), bucketId, startFileName, startFileId, maxFileCount).getResponse());
 	}
@@ -369,27 +411,83 @@ public B2DownloadFileResponse downloadFileByName(String bucketName, String fileN
 		return(new B2DownloadFileByNameRequest(getB2AuthorizeAccountResponse(), bucketName, fileName).getResponse());
 	}
 
-	public void downloadFileByIdToFile(String bucketId, String FileId, File file) {
+	public void downloadFileByIdToFile(String bucketId, String fileId, File file) throws B2ApiException {
+		try {
+			FileUtils.copyInputStreamToFile(new B2DownloadFileByIdRequest(getB2AuthorizeAccountResponse(), fileId).getResponse().getContent(), file);
+		} catch (IOException ex) {
+			throw new B2ApiException("Could not download to file", ex);
+		}
 	}
 
-	public byte[] downloadByFileIdToBytes(String bucketId, String fileId) {
-		return(new byte[] {});
+	/**
+	 * Download a file to a byte[]
+	 * 
+	 * Note: This will not return any of the headers that accompanied the download.  
+	 * See downloadFileByName to retrieve the complete response including sha1, 
+	 * content length, content type and all headers.
+	 * 
+	 * @param fileId the id of the file to download
+	 * 
+	 * @return the array of bytes for the file
+	 * 
+	 * @throws B2ApiException if there was an error with the call
+	 */
+	public byte[] downloadByFileIdToBytes(String fileId) throws B2ApiException {
+		try {
+			return(IOUtils.toByteArray(new B2DownloadFileByIdRequest(getB2AuthorizeAccountResponse(), fileId).getResponse().getContent()));
+		} catch (IOException ex) {
+			throw new B2ApiException("Could not download to bytes", ex);
+		}
 	}
 
+	/**
+	 * Download a file to an input stream
+	 * 
+	 * Note: This will not return any of the headers that accompanied the download.  
+	 * See downloadFileByName to retrieve the complete response including sha1, 
+	 * content length, content type and all headers.
+	 * 
+	 * @param fileId the id of the file to download
+	 * 
+	 * @return the input stream for the file
+	 * 
+	 * @throws B2ApiException if there was an error with the call
+	 */
 	public InputStream downloadFileByIdToStream(String fileId) throws B2ApiException {
 		return(new B2DownloadFileByIdRequest(getB2AuthorizeAccountResponse(), fileId).getResponse().getContent());
 	}
 
+	/**
+	 * Download a file 
+	 * 
+	 * @param fileId the id of the file to download
+	 * 
+	 * @return the download file response
+	 * 
+	 * @throws B2ApiException if there was an error with the call
+	 */
 	public B2DownloadFileResponse downloadFileById(String fileId) throws B2ApiException {
 		return(new B2DownloadFileByIdRequest(getB2AuthorizeAccountResponse(), fileId).getResponse());
 	}
 
+	/**
+	 * Perform a HEAD request on a file which will return the information 
+	 * associated with it. 
+	 * 
+	 * @param fileId the id of the file to retrieve the information for
+	 * 
+	 * @return the download file response
+	 * 
+	 * @throws B2ApiException if there was an error with the call
+	 */
+
 	public B2DownloadFileResponse headFileById(String fileId) throws B2ApiException {
 		return(new B2HeadFileByIdRequest(getB2AuthorizeAccountResponse(), fileId).getResponse());
 	}
 
 	/**
-	 * Return an authorize account response and cache it, or create a new one
+	 * return the authorize account response.  This is only done once and is
+	 * cached for further use.
 	 * 
 	 * @return the authorize account response
 	 * @throws B2ApiException if there was an error authenticating

src/main/java/synapticloop/b2/exception/B2ApiException.java

@@ -98,8 +98,8 @@ public String getCode() {
 	}
 
 	/**
-	 * If the original message was in valid JSON format, return the 'message' part,
-	 * else the message for the exception.
+	 * If the original message was in valid JSON format, return the 'message' 
+	 * part, else the message for the exception.
 	 * 
 	 * @return the message
 	 */
@@ -108,7 +108,8 @@ public String getMessage() {
 	}
 
 	/**
-	 * Return the original message for the exception.
+	 * Return the original message for the exception, which is a JSON formatted 
+	 * string
 	 * 
 	 * @return the original message text
 	 */

src/main/java/synapticloop/b2/package-info.java

@@ -1,5 +1,5 @@
 /**
- * This package contains the B2Api Client and enums
+ * This package contains the B2 API Client and enums
  * 
  * @author synapticloop
  *

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

@@ -108,10 +108,10 @@ protected CloseableHttpResponse executeHead() throws B2ApiException {
 			CloseableHttpResponse httpResponse = closeableHttpClient.execute(httpHead);
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 
-			LOG.debug("Received status code of:{}, for HEAD request to url '{}'", statusCode, uri);
+			LOG.debug("Received status code of: {}, for HEAD request to url '{}'", statusCode, uri);
 
 			if(statusCode != 200) {
-				throw new B2ApiException("Received status code of " + statusCode + " for request.");
+				throw new B2ApiException("Received non 'OK' status code of " + statusCode + " for request.");
 			} else {
 				return(httpResponse);
 			}
@@ -120,6 +120,13 @@ protected CloseableHttpResponse executeHead() throws B2ApiException {
 		}
 	}
 
+	/**
+	 * Execute a GET request
+	 * 
+	 * @return The response from the GET request
+	 * 
+	 * @throws B2ApiException if there was an error with the request
+	 */
 	protected String executeGet() throws B2ApiException {
 		CloseableHttpClient closeableHttpClient = HttpClients.createDefault();
 
@@ -136,7 +143,7 @@ protected String executeGet() throws B2ApiException {
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 			String response = EntityUtils.toString(httpResponse.getEntity());
 
-			LOG.debug("Received status code of:{}, for GET request to url '{}'", statusCode, url);
+			LOG.debug("Received status code of: {}, for GET request to url '{}'", statusCode, url);
 
 			if(statusCode != 200) {
 				throw new B2ApiException(response);
@@ -163,10 +170,10 @@ protected CloseableHttpResponse executeGetWithData() throws B2ApiException {
 			CloseableHttpResponse httpResponse = closeableHttpClient.execute(httpGet);
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 
-			LOG.debug("Received status code of:{}, for GET request to url '{}'", statusCode, url);
+			LOG.debug("Received status code of: {}, for GET request to url '{}'", statusCode, url);
 
 			if(statusCode != 200) {
-				throw new B2ApiException("Received status code of " + statusCode + " for request.");
+				throw new B2ApiException("Received non 'OK' status code of " + statusCode + " for request.");
 			} else {
 				return(httpResponse);
 			}
@@ -189,7 +196,7 @@ protected String executePost() throws B2ApiException {
 			CloseableHttpResponse httpResponse = closeableHttpClient.execute(httpPost);
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 
-			LOG.debug("Received status code of:{}, for POST request to url '{}'", statusCode, url);
+			LOG.debug("Received status code of: {}, for POST request to url '{}'", statusCode, url);
 
 			String response = EntityUtils.toString(httpResponse.getEntity());
 
@@ -222,7 +229,7 @@ protected String executePost(File file) throws B2ApiException {
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 			String response = EntityUtils.toString(httpResponse.getEntity());
 
-			LOG.debug("Received status code of:{}, for POST request to url '{}'", statusCode, url);
+			LOG.debug("Received status code of: {}, for POST request to url '{}'", statusCode, url);
 
 			if(statusCode != 200) {
 				throw new B2ApiException(response);

src/main/java/synapticloop/b2/util/Helper.java

@@ -14,6 +14,8 @@
 import synapticloop.b2.exception.B2ApiException;
 
 public class Helper {
+	private static final String UTF_8 = "UTF-8";
+
 	/**
 	 * Calculate and return the sha1 sum of a file
 	 * 
@@ -48,21 +50,38 @@ public static String calculateSha1(File file) throws B2ApiException {
 		}
 	}
 
-	public static String urlEncode(String s) {
+	/**
+	 * UTF-8 url encoding wrapper method.  If there was an unsupported encoding 
+	 * exception, return the un-encoded url
+	 * 
+	 * @param url the URL to encode
+	 * 
+	 * @return the encoded URL
+	 */
+	public static String urlEncode(String url) {
 		try {
-			return java.net.URLEncoder.encode(s, "UTF-8");
+			return java.net.URLEncoder.encode(url, UTF_8);
 		} catch (UnsupportedEncodingException ex) {
 			// highly unlikely
-			return(s);
+			return(url);
 		}
 	}
 
-	public static String urlDecode(String s) {
+	/**
+	 * UTF-8 url decoding wrapper method.  If there was an unsupported encoding 
+	 * exception, return the encoded url
+	 * 
+	 * @param url the URL to decode
+	 * 
+	 * @return the decoded URL
+	 */
+
+	public static String urlDecode(String url) {
 		try {
-			return java.net.URLDecoder.decode(s, "UTF-8");
+			return java.net.URLDecoder.decode(url, UTF_8);
 		} catch (UnsupportedEncodingException ex) {
 			// highly unlikey
-			return(s);
+			return(url);
 		}
 	}