added new documentation

Author: Synapticloop

README.md

@@ -1,4 +1,4 @@
-<img src="https://travis-ci.org/synapticloop/backblaze-b2-java-api.svg?branch=master" />
+[![Build Status](https://travis-ci.org/synapticloop/backblaze-b2-java-api.svg?branch=master)](https://travis-ci.org/synapticloop/backblaze-b2-java-api)
 
 A Java API for the truly excellent backblaze B2 storage
 
@@ -22,6 +22,74 @@ b2ApiClient.uploadFile(createPrivateBucket.getBucketId(), "myfile.txt", new File
 
 see [B2ApiClient.java](https://github.com/synapticloop/backblaze-b2-java-api/blob/master/src/main/java/synapticloop/b2/B2ApiClient.java) for a complete list of relatively self-explanatory methods.
 
+```
+// create a new B2ApiClient
+B2ApiClient(String, String)
+
+// create a bucket
+createBucket(String, BucketType)
+
+// delete bucket
+deleteBucket(String)
+
+// delete bucket and all containing files
+deleteBucketFully(String)
+
+// delete a version of a file
+deleteFileVersion(String, String)
+
+// download the full file by id, returning a variety of objects
+downloadFileById(String)
+downloadFileByIdToBytes(String)
+downloadFileByIdToFile(String, File)
+downloadFileByIdToStream(String)
+
+// download the full file by name, returning a variety of objects
+downloadFileByName(String, String)
+downloadFileByNameToBytes(String, String)
+downloadFileByNameToFile(String, String, File)
+downloadFileByNameToStream(String, String)
+
+// download partial content of a file by id, returning a variety of objects
+downloadFileRangeById(String, long, long)
+downloadFileRangeByIdToBytes(String, long, long)
+downloadFileRangeByIdToFile(String, File, long, long)
+downloadFileRangeByIdToStream(String, long, long)
+
+// download partial content of a file by name, returning a variety of objects
+downloadFileRangeByName(String, String, long, long)
+downloadFileRangeByNameToBytes(String, String, long, long)
+downloadFileRangeByNameToFile(String, String, File, long, long)
+downloadFileRangeByNameToStream(String, String, long, long)
+
+// retrieve information on a file
+getFileInfo(String)
+
+// return the headers associated with a file
+headFileById(String)
+
+// list all of the buckets
+listBuckets()
+
+// list file names
+listFileNames(String)
+listFileNames(String, String, Integer)
+
+// list file versions
+listFileVersions(String)
+listFileVersions(String, String)
+listFileVersions(String, String, String, Integer)
+
+// update the bucket type (private or public)
+updateBucket(String, BucketType)
+
+// upload a file
+uploadFile(String, String, File)
+uploadFile(String, String, File, Map<String, String>)
+uploadFile(String, String, File, String)
+uploadFile(String, String, File, String, Map<String, String>)
+```
+
 # Dependency Management
 
 > Note that the latest version can be found [https://bintray.com/synapticloop/maven/backblaze-b2-java-api/view](https://bintray.com/synapticloop/maven/backblaze-b2-java-api/view)

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

@@ -155,6 +155,17 @@ public List<B2BucketResponse> listBuckets() throws B2ApiException {
 		return(new B2ListBucketsRequest(getB2AuthorizeAccountResponse()).getResponse());
 	}
 
+	/**
+	 * List all of the buckets in the account that 
+	 * 
+	 * @return the list of buckets for the account
+	 * 
+	 * @throws B2ApiException if something went wrong
+	 */
+	public List<B2BucketResponse> listBuckets(String pattern) throws B2ApiException {
+		return(new B2ListBucketsRequest(getB2AuthorizeAccountResponse()).getResponse());
+	}
+
 	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 	 * 
 	 *   FILE INFORMATION API ACTIONS

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

@@ -208,7 +208,7 @@ protected String executePost() throws B2ApiException {
 
 		setHeaders(httpPost);
 
-		LOGGER.debug("POST request to URL '{}', with data of '{}'", url, postData);
+		LOGGER.debug("POST request to URL '{}', with data of '{}'", url, obfuscateData(postData));
 
 		try {
 			httpPost.setEntity(new StringEntity(postData));
@@ -351,6 +351,17 @@ private void setHeaders(HttpRequestBase httpRequestBase) {
 				httpRequestBase.setHeader(headerKey, unencodedHeaders.get(headerKey));
 			}
 		}
+	}
 
+	/**
+	 * Obfuscate the data by removing the accountId and replacing it with the
+	 * string "[redacted]"
+	 * 
+	 * @param data the data to obfuscate
+	 * 
+	 * @return the obfuscated data
+	 */
+	private String obfuscateData(String data) {
+		return(data.replaceAll("\"accountId\":\".*\"", "\"accountId\":\"[redacted]\""));
 	}
 }

src/main/java/synapticloop/b2/response/B2DownloadFileResponse.java

@@ -125,9 +125,7 @@ private void parseHeaders(CloseableHttpResponse closeableHttpResponse) throws B2
 	 * 
 	 * @return the downloaded file
 	 */
-	public InputStream getContent() {
-		return this.content;
-	}
+	public InputStream getContent() { return this.content; }
 
 	/**
 	 * Get the content length of the downloaded file

src/main/java/synapticloop/b2/response/B2HideFileResponse.java

@@ -26,19 +26,11 @@ public B2HideFileResponse(String string) throws B2ApiException {
 		this.size = jsonObject.optLong(KEY_SIZE);
 	}
 
-	public String getFileId() {
-		return this.fileId;
-	}
+	public String getFileId() { return this.fileId; }
 
-	public String getFileName() {
-		return this.fileName;
-	}
+	public String getFileName() { return this.fileName; }
 
-	public Action getAction() {
-		return this.action;
-	}
+	public Action getAction() { return this.action; }
 
-	public long getSize() {
-		return this.size;
-	}
+	public long getSize() { return this.size; }
 }

src/main/java/synapticloop/b2/response/B2ListFilesResponse.java

@@ -13,6 +13,15 @@ public class B2ListFilesResponse extends BaseB2Response {
 	private String nextFileName = null;
 	private String nextFileId = null;
 
+	/**
+	 * Instantiate a list files response with the JSON response as a 
+	 * string from the API call.  This response is then parsed into the 
+	 * relevant fields.
+	 * 
+	 * @param response the response (in JSON format)
+	 * 
+	 * @throws B2ApiException if there was an error parsing the response
+	 */
 	public B2ListFilesResponse(String string) throws B2ApiException {
 		JSONObject jsonObject = getParsedResponse(string);
 
@@ -27,7 +36,26 @@ public B2ListFilesResponse(String string) throws B2ApiException {
 		}
 	}
 
+	/**
+	 * get the next file name that is the next result to be returned after this 
+	 * result set - or null if there are no more files
+	 * 
+	 * @return the next file name to start the next iteration (or null if no next file)
+	 */
 	public String getNextFileName() { return this.nextFileName; }
+
+	/**
+	 * get the next file id that is the next result to be returned after this 
+	 * result set - or null if there are no more files
+	 * 
+	 * @return the next file id to start the next iteration (or null if no next file id)
+	 */
 	public String getNextFileId() { return this.nextFileId; }
+
+	/**
+	 * Return the list of files include file info
+	 * 
+	 * @return the list of files for this request
+	 */
 	public List<B2FileInfoResponse> getFiles() { return this.files; }
 }