Merge pull request #12 from rpmoore/master

Updating javadoc and adding missing finals

src/main/java/com/spectralogic/ds3client/commands/BulkGetRequest.java

@@ -22,7 +22,7 @@
 import java.util.List;
 
 public class BulkGetRequest extends BulkRequest {
-    public BulkGetRequest(String bucket, List<Ds3Object> objects) throws XmlProcessingException {
+    public BulkGetRequest(final String bucket, final List<Ds3Object> objects) throws XmlProcessingException {
         super(bucket, objects);
         getQueryParams().put("operation", "start_bulk_get");
     }

src/main/java/com/spectralogic/ds3client/commands/BulkGetResponse.java

@@ -21,7 +21,7 @@
 import java.io.IOException;
 
 public class BulkGetResponse extends BulkResponse {
-    public BulkGetResponse(CloseableHttpResponse response) throws IOException {
+    public BulkGetResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
     }
 }

src/main/java/com/spectralogic/ds3client/commands/BulkPutRequest.java

@@ -22,7 +22,7 @@
 import java.util.List;
 
 public class BulkPutRequest extends BulkRequest {
-    public BulkPutRequest(String bucket, List<Ds3Object> objects) throws XmlProcessingException {
+    public BulkPutRequest(final String bucket, final List<Ds3Object> objects) throws XmlProcessingException {
         super(bucket, objects);
         getQueryParams().put("operation", "start_bulk_put");
     }

src/main/java/com/spectralogic/ds3client/commands/BulkPutResponse.java

@@ -20,7 +20,7 @@
 import java.io.IOException;
 
 public class BulkPutResponse extends BulkResponse {
-    public BulkPutResponse(CloseableHttpResponse response) throws IOException {
+    public BulkPutResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
     }
 }

src/main/java/com/spectralogic/ds3client/commands/BulkResponse.java

@@ -26,7 +26,7 @@
 
 public abstract class BulkResponse extends AbstractResponse {
     private MasterObjectList result;
-    public BulkResponse(CloseableHttpResponse response) throws IOException {
+    public BulkResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
     }
 

src/main/java/com/spectralogic/ds3client/commands/DeleteBucketResponse.java

@@ -20,7 +20,7 @@
 import java.io.IOException;
 
 public class DeleteBucketResponse extends AbstractResponse{
-    public DeleteBucketResponse(CloseableHttpResponse response) throws IOException {
+    public DeleteBucketResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
     }
 

src/main/java/com/spectralogic/ds3client/commands/DeleteObjectResponse.java

@@ -20,7 +20,7 @@
 import java.io.IOException;
 
 public class DeleteObjectResponse extends AbstractResponse {
-    public DeleteObjectResponse(CloseableHttpResponse response) throws IOException {
+    public DeleteObjectResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
     }
 

src/main/java/com/spectralogic/ds3client/commands/GetBucketResponse.java

@@ -28,7 +28,7 @@ public class GetBucketResponse extends AbstractResponse {
 
     private ListBucketResult result;
 
-    public GetBucketResponse(CloseableHttpResponse response) throws IOException {
+    public GetBucketResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
 
     }

src/main/java/com/spectralogic/ds3client/commands/GetObjectResponse.java

@@ -24,7 +24,7 @@ public class GetObjectResponse extends AbstractResponse {
 
     private InputStream content;
 
-    public GetObjectResponse(CloseableHttpResponse response) throws IOException {
+    public GetObjectResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
     }
 

src/main/java/com/spectralogic/ds3client/commands/GetServiceResponse.java

@@ -28,7 +28,7 @@ public class GetServiceResponse extends AbstractResponse {
 
     private ListAllMyBucketsResult result;
 
-    public GetServiceResponse(CloseableHttpResponse response) throws IOException {
+    public GetServiceResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
     }
 

src/main/java/com/spectralogic/ds3client/commands/PutBucketResponse.java

@@ -20,7 +20,7 @@
 import java.io.IOException;
 
 public class PutBucketResponse extends AbstractResponse {
-    public PutBucketResponse(CloseableHttpResponse response) throws IOException {
+    public PutBucketResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
     }
 

src/main/java/com/spectralogic/ds3client/commands/PutObjectResponse.java

@@ -20,7 +20,7 @@
 import java.io.IOException;
 
 public class PutObjectResponse extends AbstractResponse {
-    public PutObjectResponse(CloseableHttpResponse response) throws IOException {
+    public PutObjectResponse(final CloseableHttpResponse response) throws IOException {
         super(response);
     }
 

src/main/java/com/spectralogic/ds3client/helpers/Ds3ClientHelpers.java

@@ -41,6 +41,9 @@
 import com.spectralogic.ds3client.models.MasterObjectList;
 import com.spectralogic.ds3client.serializer.XmlProcessingException;
 
+/**
+ * A wrapper around the {@link com.spectralogic.ds3client.Ds3Client} which automates common tasks.
+ */
 public class Ds3ClientHelpers {
     private static final int DEFAULT_MAX_KEYS = 1000;
 
@@ -50,8 +53,6 @@ public interface ObjectGetter {
         /**
          * Must save the {@code contents} for the given {@code key}.
          * 
-         * @param key
-         * @param contents
          * @throws IOException
          */
         public void writeContents(String key, InputStream contents) throws IOException;
@@ -61,8 +62,6 @@ public interface ObjectPutter {
         /**
          * Must return the contents to send over DS3 for the given {@code key}.
          * 
-         * @param key
-         * @return
          * @throws IOException
          */
         public InputStream getContent(String key) throws IOException;
@@ -80,10 +79,9 @@ public interface Job {
 
     public interface WriteJob extends Job {
         /**
-         * Calls the given @{code putter} for each object in the job remaining to be written.
+         * Calls the given {@code putter} for each object in the job remaining to be written.
          * Note that it's possible for the {@code putter} to be called simultaneously from multiple threads.
          * 
-         * @param putter
          * @throws SignatureException
          * @throws IOException
          * @throws XmlProcessingException
@@ -93,28 +91,27 @@ public interface WriteJob extends Job {
 
     public interface ReadJob extends Job {
         /**
-         * Calls the given @{code getter} for each object in the job remaining to be read.
+         * Calls the given {@code getter} for each object in the job remaining to be read.
          * Note that it's possible for the {@code getter} to be called simultaneously from multiple threads.
          * 
-         * @param putter
          * @throws SignatureException
          * @throws IOException
          * @throws XmlProcessingException
          */
         public void read(ObjectGetter getter) throws SignatureException, IOException, XmlProcessingException;
     }
 
+    /**
+     * Wraps the given {@link com.spectralogic.ds3client.Ds3Client} with helper methods.
+     */
     public Ds3ClientHelpers(final Ds3Client client) {
         this.client = client;
     }
 
     /**
-     * Performs a bulk put job creation request and returns an @{code IWriteJob}.
-     * See {@code IWriteJob} for information on how to write the objects for the job.
+     * Performs a bulk put job creation request and returns an {@link WriteJob}.
+     * See {@link WriteJob} for information on how to write the objects for the job.
      * 
-     * @param bucket
-     * @param objectsToWrite
-     * @return
      * @throws SignatureException
      * @throws IOException
      * @throws XmlProcessingException
@@ -128,12 +125,9 @@ public WriteJob startWriteJob(final String bucket, final Iterable<Ds3Object> obj
     }
 
     /**
-     * Performs a bulk get job creation request and returns an @{code IReadJob}.
-     * See {@code IReadJob} for information on how to read the objects for the job.
+     * Performs a bulk get job creation request and returns an {@link ReadJob}.
+     * See {@link ReadJob} for information on how to read the objects for the job.
      * 
-     * @param bucket
-     * @param objectsToRead
-     * @return
      * @throws SignatureException
      * @throws IOException
      * @throws XmlProcessingException
@@ -147,10 +141,8 @@ public ReadJob startReadJob(final String bucket, final Iterable<Ds3Object> objec
     }
 
     /**
-     * Performs a bulk get job creation request for all of the objects in the given bucket and returns an @{code IReadJob}.
+     * Performs a bulk get job creation request for all of the objects in the given bucket and returns an {@link ReadJob}.
      * 
-     * @param bucket
-     * @return
      * @throws SignatureException
      * @throws IOException
      * @throws XmlProcessingException
@@ -170,8 +162,6 @@ public ReadJob startReadAllJob(final String bucket)
     /**
      * Returns information about all of the objects in the bucket, regardless of how many objects the bucket contains.
      * 
-     * @param bucket
-     * @return
      * @throws SignatureException
      * @throws IOException
      */
@@ -182,9 +172,6 @@ public Iterable<Contents> listObjects(final String bucket) throws SignatureExcep
     /**
      * Returns information about all of the objects in the bucket, regardless of how many objects the bucket contains.
      * 
-     * @param bucket
-     * @param keyPrefix
-     * @return
      * @throws SignatureException
      * @throws IOException
      */
@@ -195,10 +182,6 @@ public Iterable<Contents> listObjects(final String bucket, final String keyPrefi
     /**
      * Returns information about all of the objects in the bucket, regardless of how many objects the bucket contains.
      * 
-     * @param bucket
-     * @param keyPrefix
-     * @param maxKeys
-     * @return
      * @throws SignatureException
      * @throws IOException
      */
@@ -239,8 +222,6 @@ public Iterable<Contents> listObjects(final String bucket, final String keyPrefi
      * Returns an object list with which you can call {@code startWriteJob} based on the files in a {@code directory}.
      * This method traverses the {@code directory} recursively.
      * 
-     * @param directory
-     * @return
      * @throws IOException
      */
     public Iterable<Ds3Object> listObjectsForDirectory(final Path directory) throws IOException {

src/main/java/com/spectralogic/ds3client/helpers/FileObjectGetter.java

@@ -26,9 +26,16 @@
 
 import com.spectralogic.ds3client.helpers.Ds3ClientHelpers.ObjectGetter;
 
+/**
+ * Writes files to the local file system preserving the path.
+ */
 public class FileObjectGetter implements ObjectGetter {
     private final Path root;
 
+    /**
+     * Creates a new FileObjectGetter to retrieve files from a remote DS3 system to the local file system.
+     * @param root The {@code root} directory of the local file system for all files being transferred.
+     */
     public FileObjectGetter(final Path root) {
         this.root = root;
     }

src/main/java/com/spectralogic/ds3client/helpers/FileObjectPutter.java

@@ -23,10 +23,16 @@
 
 import com.spectralogic.ds3client.helpers.Ds3ClientHelpers.ObjectPutter;
 
-
+/**
+ * Writes files to a remote DS3 appliance from a directory in the local filesystem.
+ */
 public class FileObjectPutter implements ObjectPutter {
     private final Path root;
 
+    /**
+     * Creates a new FileObjectPutter given a directory in the local file system.
+     * @param root The {@code root} directory for all the files being transferred.
+     */
     public FileObjectPutter(final Path root) {
         this.root = root;
     }

src/main/java/com/spectralogic/ds3client/helpers/package-info.java

@@ -0,0 +1,19 @@
+/*
+ * ******************************************************************************
+ *   Copyright 2014 Spectra Logic Corporation. All Rights Reserved.
+ *   Licensed under the Apache License, Version 2.0 (the "License"). You may not use
+ *   this file except in compliance with the License. A copy of the License is located at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   or in the "license" file accompanying this file.
+ *   This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ *   CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ *   specific language governing permissions and limitations under the License.
+ * ****************************************************************************
+ */
+
+/**
+ * This package contains helper methods to automate common tasks with the SDK.
+ */
+package com.spectralogic.ds3client.helpers;