added ranges to the methods, updated documentation

Author: Synapticloop

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.2'
+version = 'v1.1.0'
 
 description = """backblaze-b2-java-api"""
 

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

@@ -20,12 +20,49 @@
 public class B2DownloadFileByIdRequest extends BaseB2Request {
 	private static final String B2_DOWNLOAD_FILE_BY_ID = BASE_API_VERSION + "b2_download_file_by_id";
 
+	/**
+	 * Create a download file by ID request to download the complete file
+	 * 
+	 * @param b2AuthorizeAccountResponse The authorize account response
+	 * @param fileId the unique id of the file
+	 */
 	public B2DownloadFileByIdRequest(B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String fileId) {
 		super(b2AuthorizeAccountResponse);
 		url = b2AuthorizeAccountResponse.getDownloadUrl() + B2_DOWNLOAD_FILE_BY_ID;
 		parameters.put(KEY_FILE_ID, fileId);
 	}
 
+	/**
+	 * Create a download file by ID request to download the range of bytes 
+	 * between rangeStart and rangeEnd (inclusive)
+	 * 
+	 * 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 b2AuthorizeAccountResponse The authorize account response
+	 * @param fileId the unique id of the file
+	 * @param rangeStart the start of the range
+	 * @param rangeEnd the end of the range
+	 */
+	public B2DownloadFileByIdRequest(B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String fileId, long rangeStart, long rangeEnd) {
+		this(b2AuthorizeAccountResponse, fileId);
+		unencodedHeaders.put(KEY_RANGE, "bytes=" + rangeStart + "-" + rangeEnd);
+	}
+
+	/**
+	 * Execute the request and return the response
+	 * 
+	 * @return The download file response
+	 * 
+	 * @throws B2ApiException If there was an error with the call
+	 */
 	public B2DownloadFileResponse getResponse() throws B2ApiException {
 		return(new B2DownloadFileResponse(executeGetWithData()));
 	}

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

@@ -26,6 +26,11 @@ public B2DownloadFileByNameRequest(B2AuthorizeAccountResponse b2AuthorizeAccount
 		url = b2AuthorizeAccountResponse.getDownloadUrl() + "/file/" + Helper.urlEncode(bucketName) + "/" + Helper.urlEncode(fileName);
 	}
 
+	public B2DownloadFileByNameRequest(B2AuthorizeAccountResponse b2AuthorizeAccountResponse, String bucketName, String fileName, long rangeStart, long rangeEnd) {
+		this(b2AuthorizeAccountResponse, bucketName, fileName);
+		unencodedHeaders.put(KEY_RANGE, "bytes=" + rangeStart + "-" + rangeEnd);
+	}
+
 	public B2DownloadFileResponse getResponse() throws B2ApiException {
 		return(new B2DownloadFileResponse(executeGetWithData()));
 	}

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

@@ -30,7 +30,7 @@
 import synapticloop.b2.util.Helper;
 
 public class BaseB2Request {
-	private static final Logger LOG = LoggerFactory.getLogger(BaseB2Request.class);
+	private static final Logger LOGGER = LoggerFactory.getLogger(BaseB2Request.class);
 
 	protected static final String BASE_API_HOST = "https://api.backblaze.com";
 	protected static final String BASE_API_VERSION = "/b2api/v1/";
@@ -53,6 +53,7 @@ public class BaseB2Request {
 	protected static final String KEY_FILE_ID = "fileId";
 	protected static final String KEY_FILE_NAME = "fileName";
 	protected static final String KEY_MAX_FILE_COUNT = "maxFileCount";
+	protected static final String KEY_RANGE = "Range";
 	protected static final String KEY_START_FILE_ID = "startFileId";
 	protected static final String KEY_START_FILE_NAME = "startFileName";
 
@@ -100,15 +101,15 @@ protected CloseableHttpResponse executeHead() throws B2ApiException {
 		try {
 			URI uri = getUri();
 
-			LOG.debug("HEAD request to URL '{}'", uri.toString());
+			LOGGER.debug("HEAD request to URL '{}'", uri.toString());
 
 			HttpHead httpHead = new HttpHead(uri);
 			setHeaders(httpHead);
 
 			CloseableHttpResponse httpResponse = closeableHttpClient.execute(httpHead);
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 
-			LOG.debug("Received status code of: {}, for HEAD request to url '{}'", statusCode, uri);
+			LOGGER.debug("Received status code of: {}, for HEAD request to url '{}'", statusCode, uri);
 
 			if(statusCode != 200) {
 				throw new B2ApiException("Received non 'OK' status code of " + statusCode + " for request.");
@@ -121,7 +122,7 @@ protected CloseableHttpResponse executeHead() throws B2ApiException {
 	}
 
 	/**
-	 * Execute a GET request
+	 * Execute a GET request, returning the string representation of the response
 	 * 
 	 * @return The response from the GET request
 	 * 
@@ -136,16 +137,17 @@ protected String executeGet() throws B2ApiException {
 			HttpGet httpGet = new HttpGet(uri);
 			setHeaders(httpGet);
 
-			LOG.debug("GET request to URL '{}'", url);
+			LOGGER.debug("GET request to URL '{}'", url);
 
 
 			CloseableHttpResponse httpResponse = closeableHttpClient.execute(httpGet);
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 			String response = EntityUtils.toString(httpResponse.getEntity());
 
-			LOG.debug("Received status code of: {}, for GET request to url '{}'", statusCode, url);
+			LOGGER.debug("Received status code of: {}, for GET request to url '{}'", statusCode, url);
 
-			if(statusCode != 200) {
+			// you will either get an OK or a partial content
+			if(statusCode != 200 && statusCode != 206) {
 				throw new B2ApiException(response);
 			} else {
 				return(response);
@@ -156,23 +158,32 @@ protected String executeGet() throws B2ApiException {
 	}
 
 
+	/**
+	 * Execute a GET request, returning the data stream from the response.
+	 * 
+	 * @return the response from the get request
+	 * 
+	 * @throws B2ApiException if there was an error with the call, most notably
+	 *     a non OK status code (i.e. not 200)
+	 */
 	protected CloseableHttpResponse executeGetWithData() throws B2ApiException {
 		CloseableHttpClient closeableHttpClient = HttpClients.createDefault();
 
 		try {
 			URI uri = getUri();
 
-			LOG.debug("GET request to URL '{}'", uri.toString());
+			LOGGER.debug("GET request to URL '{}'", uri.toString());
 
 			HttpGet httpGet = new HttpGet(uri);
 			setHeaders(httpGet);
 
 			CloseableHttpResponse httpResponse = closeableHttpClient.execute(httpGet);
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 
-			LOG.debug("Received status code of: {}, for GET request to url '{}'", statusCode, url);
+			LOGGER.debug("Received status code of: {}, for GET request to url '{}'", statusCode, url);
 
-			if(statusCode != 200) {
+			// you will either get an OK or a partial content
+			if(statusCode != 200 && statusCode != 206) {
 				throw new B2ApiException("Received non 'OK' status code of " + statusCode + " for request.");
 			} else {
 				return(httpResponse);
@@ -182,21 +193,29 @@ protected CloseableHttpResponse executeGetWithData() throws B2ApiException {
 		}
 	}
 
+	/**
+	 * Execute a POST request returning the response data as a String
+	 * 
+	 * @return the response data as a string
+	 * 
+	 * @throws B2ApiException if there was an error with the call, most notably
+	 *     a non OK status code (i.e. not 200)
+	 */
 	protected String executePost() throws B2ApiException {
 		CloseableHttpClient closeableHttpClient = HttpClients.createDefault();
 		String postData = convertPostData();
 		HttpPost httpPost = new HttpPost(url);
 
 		setHeaders(httpPost);
 
-		LOG.debug("POST request to URL '{}', with data of '{}'", url, postData);
+		LOGGER.debug("POST request to URL '{}', with data of '{}'", url, postData);
 
 		try {
 			httpPost.setEntity(new StringEntity(postData));
 			CloseableHttpResponse httpResponse = closeableHttpClient.execute(httpPost);
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 
-			LOG.debug("Received status code of: {}, for POST request to url '{}'", statusCode, url);
+			LOGGER.debug("Received status code of: {}, for POST request to url '{}'", statusCode, url);
 
 			String response = EntityUtils.toString(httpResponse.getEntity());
 
@@ -215,21 +234,31 @@ protected String executePost() throws B2ApiException {
 		}
 	}
 
+	/**
+	 * Execute a POST request with the contents of a file.
+	 * 
+	 * @param file the file to post
+	 * 
+	 * @return the string representation of the response
+	 * 
+	 * @throws B2ApiException if there was an error with the call, most notably
+	 *     a non OK status code (i.e. not 200)
+	 */
 	protected String executePost(File file) throws B2ApiException {
 		CloseableHttpClient closeableHttpClient = HttpClients.createDefault();
 		HttpPost httpPost = new HttpPost(url);
 
 		setHeaders(httpPost);
 
-		LOG.debug("POST request to URL '{}', with file", url);
+		LOGGER.debug("POST request to URL '{}', with file", url);
 
 		try {
 			httpPost.setEntity(new FileEntity(file));
 			CloseableHttpResponse httpResponse = closeableHttpClient.execute(httpPost);
 			int statusCode = httpResponse.getStatusLine().getStatusCode();
 			String response = EntityUtils.toString(httpResponse.getEntity());
 
-			LOG.debug("Received status code of: {}, for POST request to url '{}'", statusCode, url);
+			LOGGER.debug("Received status code of: {}, for POST request to url '{}'", statusCode, url);
 
 			if(statusCode != 200) {
 				throw new B2ApiException(response);
@@ -298,7 +327,8 @@ private URI getUri() throws URISyntaxException {
 	/**
 	 * Set the headers safely, go through the headers Map and add them to the http 
 	 * request with properly encode values.  If they already exist on the http 
-	 * request, it will be ignored.
+	 * request, it will be ignored.  Then go through the unencodedHeaders Map and
+	 * add them to the http request with no encoding done on the header values.
 	 * 
 	 * To over-ride what headers are set, this should be done in the constructor 
 	 * of the base request object.
@@ -309,14 +339,15 @@ private void setHeaders(HttpRequestBase httpRequestBase) {
 		Set<String> headerKeySet = headers.keySet();
 		for (String headerKey : headerKeySet) {
 			if(!httpRequestBase.containsHeader(headerKey)) {
-				LOG.trace("Setting header '" + headerKey + "'.");
+				LOGGER.trace("Setting header (encoded) '" + headerKey + "'.");
 				httpRequestBase.setHeader(headerKey, Helper.urlEncode(headers.get(headerKey)));
 			}
 		}
+
 		headerKeySet = unencodedHeaders.keySet();
 		for (String headerKey : headerKeySet) {
 			if(!httpRequestBase.containsHeader(headerKey)) {
-				LOG.trace("Setting unencoded header '" + headerKey + "'.");
+				LOGGER.trace("Setting header (un-encoded) '" + headerKey + "'.");
 				httpRequestBase.setHeader(headerKey, unencodedHeaders.get(headerKey));
 			}
 		}