diff --git a/src/main/java/com/spectralogic/ds3client/helpers/Ds3ClientHelpers.java b/src/main/java/com/spectralogic/ds3client/helpers/Ds3ClientHelpers.java index 53a90144b..5514fda64 100644 --- a/src/main/java/com/spectralogic/ds3client/helpers/Ds3ClientHelpers.java +++ b/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,10 +91,9 @@ 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 @@ -104,17 +101,17 @@ public interface ReadJob extends Job { 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 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 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 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 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 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 listObjectsForDirectory(final Path directory) throws IOException { diff --git a/src/main/java/com/spectralogic/ds3client/helpers/FileObjectGetter.java b/src/main/java/com/spectralogic/ds3client/helpers/FileObjectGetter.java index 1113fc3bb..9150fddd9 100644 --- a/src/main/java/com/spectralogic/ds3client/helpers/FileObjectGetter.java +++ b/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; } diff --git a/src/main/java/com/spectralogic/ds3client/helpers/FileObjectPutter.java b/src/main/java/com/spectralogic/ds3client/helpers/FileObjectPutter.java index 1155a3531..6577b5b12 100644 --- a/src/main/java/com/spectralogic/ds3client/helpers/FileObjectPutter.java +++ b/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; } diff --git a/src/main/java/com/spectralogic/ds3client/helpers/package-info.java b/src/main/java/com/spectralogic/ds3client/helpers/package-info.java new file mode 100644 index 000000000..6d97af424 --- /dev/null +++ b/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;