Merge pull request #354 from rpmoore/lazy_loader_documentation

Lazy loader documentation

Author: RachelTucker

docker/docker-compose.yml

@@ -19,6 +19,3 @@ services:
             - GIT_BRANCH
         dns:
             - 10.1.0.9
-
-
-

ds3-sdk/src/main/java/com/spectralogic/ds3client/helpers/pagination/PaginatingCommand.java

@@ -21,8 +21,25 @@
 import java.io.IOException;
 import java.util.List;
 
+/**
+ * This interface is used to implement the call specific logic for any Spectra S3 paginated request.
+ * @param <E> The type the iterator will return.
+ * @param <T> The {@link AbstractPaginationRequest} that the command will invoke
+ * @param <F> The {@link AbstractPaginationResponse} that will be returned by the {@link AbstractPaginationRequest}
+ */
 public interface PaginatingCommand<E, T extends AbstractPaginationRequest, F extends AbstractPaginationResponse> {
+    /**
+     * Creates an initial request.  This should not modify any of the pagination values for the request
+     */
     T createRequest();
+
+    /**
+     * Invokes the request and returns the response
+     */
     F invokeCommand(final T paginationRequest) throws IOException;
+
+    /**
+     * Parses the response into the correct payload to be consumed by the iterator
+     */
     List<E> getResponseContents(F response);
 }

ds3-sdk/src/main/java/com/spectralogic/ds3client/helpers/pagination/SpectraS3PaginationLoader.java

@@ -25,6 +25,13 @@
 import java.util.Collections;
 import java.util.List;
 
+/**
+ * This class is used as the base implementation for all Spectra S3 paginating calls.  It requires a {@link PaginatingCommand} which implements the
+ * call specific logic for each paginated request.
+ * @param <T> The type returned by the iterator
+ * @param <E> The {@link com.spectralogic.ds3client.commands.interfaces.AbstractPaginationRequest} this loader will invoke
+ * @param <F> The {@link com.spectralogic.ds3client.commands.interfaces.AbstractPaginationResponse} that the {@link com.spectralogic.ds3client.commands.interfaces.AbstractPaginationRequest} will return.
+ */
 public class SpectraS3PaginationLoader<T, E extends AbstractPaginationRequest, F extends AbstractPaginationResponse> implements LazyIterable.LazyLoader<T> {
 
     private final PaginatingCommand<T, E, F> paginatingCommand;

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

@@ -0,0 +1,21 @@
+/*
+ * ******************************************************************************
+ *   Copyright 2014-2016 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 many base implementations for supporting Spectra S3 calls that
+ * can be paginated.
+ */
+package com.spectralogic.ds3client.helpers.pagination;
+

ds3-sdk/src/main/java/com/spectralogic/ds3client/utils/collections/LazyIterable.java

@@ -25,6 +25,8 @@
  * Produces an Iterator that will lazily load content.
  * Our definition of lazy for this class, is that the Iterator is returned right
  * away with no data.  Data is only then loaded, as needed, in pieces as defined by the LazyIterableLoader.
+ *
+ * To use, supply a {@link LazyLoaderFactory} which is used to fetch data as it is needed.
  */
 public class LazyIterable<T> implements Iterable<T> {
 
@@ -39,10 +41,23 @@ public Iterator<T> iterator() {
         return new LazyObjectIterator<>(lazyLoaderFactory.create());
     }
 
+    /**
+     * A factory that creates instances of LazyLoaders.  It's important that this factory
+     * does not return the same loader, otherwise every iterator created with this factory
+     * will share the same state and can lead to undefined behavior.
+     * @param <T> The model that is returned by the iterator
+     */
     public interface LazyLoaderFactory<T> {
         LazyLoader<T> create();
     }
 
+    /**
+     * A loader is responsible for returning new data on each call to {@link LazyLoader#getNextValues()}.
+     *
+     * If using a Spectra S3 API call see {@link com.spectralogic.ds3client.helpers.pagination.SpectraS3PaginationLoader}
+     * as the base implementation to handle most of the details of creating a new LazyLoader
+     * @param <T> The model that is returned by the iterator
+     */
     public interface LazyLoader<T> {
         List<T> getNextValues();
     }
@@ -97,6 +112,5 @@ private void loadCache() {
         public void remove() {
             throw new UnsupportedOperationException("The remove method on the LazyObjectIterator is not supported");
         }
-
     }
 }