Adding more javadoc. Updating some of the existing javadoc to remove …

…warnings.

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;