You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by bo...@apache.org on 2018/04/30 14:53:48 UTC
commons-compress git commit: fix javadoc warnings
Repository: commons-compress
Updated Branches:
refs/heads/master 75a7edc74 -> 78cf6565c
fix javadoc warnings
Project: http://git-wip-us.apache.org/repos/asf/commons-compress/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-compress/commit/78cf6565
Tree: http://git-wip-us.apache.org/repos/asf/commons-compress/tree/78cf6565
Diff: http://git-wip-us.apache.org/repos/asf/commons-compress/diff/78cf6565
Branch: refs/heads/master
Commit: 78cf6565c6c000de7eb61456454717523c4e6966
Parents: 75a7edc
Author: Stefan Bodewig <bo...@apache.org>
Authored: Mon Apr 30 16:53:19 2018 +0200
Committer: Stefan Bodewig <bo...@apache.org>
Committed: Mon Apr 30 16:53:19 2018 +0200
----------------------------------------------------------------------
.../commons/compress/archivers/Archiver.java | 38 ++++++++++++++------
.../commons/compress/archivers/Expander.java | 34 +++++++++++++++++-
.../compress/archivers/examples/Archive.java | 17 +++++++++
.../archivers/examples/ArchiveEntrySource.java | 2 ++
.../archivers/examples/ArchiveSinks.java | 27 ++++++++++++--
.../archivers/examples/ArchiveSources.java | 33 +++++++++++++++--
.../compress/archivers/examples/Chain.java | 12 +++++++
.../archivers/examples/ChainPayload.java | 8 ++++-
.../compress/archivers/examples/ChainStep.java | 2 ++
.../examples/DirectoryBasedSource.java | 3 ++
.../archivers/examples/DirectorySink.java | 4 +++
.../compress/archivers/examples/Expand.java | 13 +++++++
.../archivers/examples/FileToArchiveSink.java | 2 ++
.../compress/archivers/examples/Filter.java | 2 +-
.../compress/archivers/examples/Sink.java | 7 ++++
.../compress/archivers/examples/Supplier.java | 7 ++++
.../commons/compress/utils/BitInputStream.java | 1 +
17 files changed, 193 insertions(+), 19 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/Archiver.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/Archiver.java b/src/main/java/org/apache/commons/compress/archivers/Archiver.java
index dacbd74..4e82640 100644
--- a/src/main/java/org/apache/commons/compress/archivers/Archiver.java
+++ b/src/main/java/org/apache/commons/compress/archivers/Archiver.java
@@ -68,7 +68,9 @@ public class Archiver {
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
* @param target the file to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public void create(String format, File target, File directory) throws IOException, ArchiveException {
create(format, target, directory, ACCEPT_ALL);
@@ -82,8 +84,10 @@ public class Archiver {
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
* @param target the file to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
* @param filter selects the files and directories to include inside the archive.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public void create(String format, File target, File directory, FileFilter filter)
throws IOException, ArchiveException {
@@ -107,7 +111,9 @@ public class Archiver {
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
* @param target the stream to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public void create(String format, OutputStream target, File directory) throws IOException, ArchiveException {
create(format, target, directory, ACCEPT_ALL);
@@ -121,8 +127,10 @@ public class Archiver {
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
* @param target the stream to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
* @param filter selects the files and directories to include inside the archive.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public void create(String format, OutputStream target, File directory, FileFilter filter)
throws IOException, ArchiveException {
@@ -137,7 +145,9 @@ public class Archiver {
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
* @param target the channel to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public void create(String format, SeekableByteChannel target, File directory)
throws IOException, ArchiveException {
@@ -152,8 +162,10 @@ public class Archiver {
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
* @param target the channel to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
* @param filter selects the files and directories to include inside the archive.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public void create(String format, SeekableByteChannel target, File directory, FileFilter filter)
throws IOException, ArchiveException {
@@ -173,7 +185,9 @@ public class Archiver {
* files and directories in {@code directory}.
*
* @param target the stream to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public void create(ArchiveOutputStream target, File directory) throws IOException, ArchiveException {
create(target, directory, ACCEPT_ALL);
@@ -185,8 +199,10 @@ public class Archiver {
* {@code filter}.
*
* @param target the stream to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
* @param filter selects the files and directories to include inside the archive.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public void create(final ArchiveOutputStream target, File directory, FileFilter filter)
throws IOException, ArchiveException {
@@ -216,7 +232,8 @@ public class Archiver {
* files and directories in {@code directory}.
*
* @param target the file to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
+ * @throws IOException if an I/O error occurs
*/
public void create(final SevenZOutputFile target, File directory) throws IOException {
create(target, directory, ACCEPT_ALL);
@@ -228,8 +245,9 @@ public class Archiver {
* {@code filter}.
*
* @param target the file to write the new archive to.
- * @param the directory that contains the files to archive.
+ * @param directory the directory that contains the files to archive.
* @param filter selects the files and directories to include inside the archive.
+ * @throws IOException if an I/O error occurs
*/
public void create(final SevenZOutputFile target, File directory, FileFilter filter) throws IOException {
create(directory, filter, new ArchiveEntryCreator() {
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/Expander.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/Expander.java b/src/main/java/org/apache/commons/compress/archivers/Expander.java
index 5f66965..82b958e 100644
--- a/src/main/java/org/apache/commons/compress/archivers/Expander.java
+++ b/src/main/java/org/apache/commons/compress/archivers/Expander.java
@@ -47,6 +47,7 @@ public class Expander {
public interface ArchiveEntryFilter {
/**
* @return true if the entry shall be expanded
+ * @param entry the entry to test
*/
boolean accept(ArchiveEntry entry);
}
@@ -73,6 +74,8 @@ public class Expander {
*
* @param archive the file to expand
* @param targetDirectory the directory to write to
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(File archive, File targetDirectory) throws IOException, ArchiveException {
expand(archive, targetDirectory, ACCEPT_ALL);
@@ -85,6 +88,8 @@ public class Expander {
* @param targetDirectory the directory to write to
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(String format, File archive, File targetDirectory) throws IOException, ArchiveException {
expand(format, archive, targetDirectory, ACCEPT_ALL);
@@ -99,6 +104,8 @@ public class Expander {
* @param archive the file to expand
* @param targetDirectory the directory to write to
* @param filter selects the entries to expand
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(File archive, File targetDirectory, ArchiveEntryFilter filter)
throws IOException, ArchiveException {
@@ -118,6 +125,8 @@ public class Expander {
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
* @param filter selects the entries to expand
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(String format, File archive, File targetDirectory, ArchiveEntryFilter filter)
throws IOException, ArchiveException {
@@ -139,6 +148,8 @@ public class Expander {
*
* @param archive the file to expand
* @param targetDirectory the directory to write to
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(InputStream archive, File targetDirectory) throws IOException, ArchiveException {
expand(archive, targetDirectory, ACCEPT_ALL);
@@ -151,6 +162,8 @@ public class Expander {
* @param targetDirectory the directory to write to
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(String format, InputStream archive, File targetDirectory)
throws IOException, ArchiveException {
@@ -166,6 +179,8 @@ public class Expander {
* @param archive the file to expand
* @param targetDirectory the directory to write to
* @param filter selects the entries to expand
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(InputStream archive, File targetDirectory, ArchiveEntryFilter filter)
throws IOException, ArchiveException {
@@ -181,6 +196,8 @@ public class Expander {
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
* @param filter selects the entries to expand
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(String format, InputStream archive, File targetDirectory, ArchiveEntryFilter filter)
throws IOException, ArchiveException {
@@ -194,6 +211,8 @@ public class Expander {
* @param targetDirectory the directory to write to
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(String format, SeekableByteChannel archive, File targetDirectory)
throws IOException, ArchiveException {
@@ -206,10 +225,11 @@ public class Expander {
*
* @param archive the file to expand
* @param targetDirectory the directory to write to
- * @param the format of the archive
* @param format the archive format. This uses the same format as
* accepted by {@link ArchiveStreamFactory}.
* @param filter selects the entries to expand
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(String format, SeekableByteChannel archive, File targetDirectory, ArchiveEntryFilter filter)
throws IOException, ArchiveException {
@@ -229,6 +249,8 @@ public class Expander {
*
* @param archive the file to expand
* @param targetDirectory the directory to write to
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(ArchiveInputStream archive, File targetDirectory)
throws IOException, ArchiveException {
@@ -242,6 +264,8 @@ public class Expander {
* @param archive the file to expand
* @param targetDirectory the directory to write to
* @param filter selects the entries to expand
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(final ArchiveInputStream archive, File targetDirectory, ArchiveEntryFilter filter)
throws IOException, ArchiveException {
@@ -267,6 +291,8 @@ public class Expander {
*
* @param archive the file to expand
* @param targetDirectory the directory to write to
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(ZipFile archive, File targetDirectory)
throws IOException, ArchiveException {
@@ -280,6 +306,8 @@ public class Expander {
* @param archive the file to expand
* @param targetDirectory the directory to write to
* @param filter selects the entries to expand
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(final ZipFile archive, File targetDirectory, ArchiveEntryFilter filter)
throws IOException, ArchiveException {
@@ -308,6 +336,8 @@ public class Expander {
*
* @param archive the file to expand
* @param targetDirectory the directory to write to
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(SevenZFile archive, File targetDirectory)
throws IOException, ArchiveException {
@@ -321,6 +351,8 @@ public class Expander {
* @param archive the file to expand
* @param targetDirectory the directory to write to
* @param filter selects the entries to expand
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public void expand(final SevenZFile archive, File targetDirectory, ArchiveEntryFilter filter)
throws IOException, ArchiveException {
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/Archive.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/Archive.java b/src/main/java/org/apache/commons/compress/archivers/examples/Archive.java
index 8b5a5d2..1895a7d 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/Archive.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/Archive.java
@@ -35,36 +35,51 @@ public class Archive {
public interface ChainBuilder {
/**
* Adds a filter to the chain.
+ * @param filter the filter to apply
+ * @return an updated builder
*/
ChainBuilder filter(Filter<File> filter);
/**
* Adds a filter to the chain.
+ * @param filter the filter to apply
+ * @return an updated builder
*/
ChainBuilder filter(FileFilter filter);
/**
* Adds a filter to the chain that filters out entries that cannot be read.
+ * @return an updated builder
*/
ChainBuilder skipUnreadable();
/**
* Adds a filter to the chain that filters out everything that is not a file.
+ * @return an updated builder
*/
ChainBuilder skipNonFiles();
/**
* Adds a transformer to the chain.
+ * @param transformer transformer to apply
+ * @return an updated builder
*/
ChainBuilder map(Transformer<File> transformer);
/**
* Adds a generic step to the chain.
+ * @param step step to perform
+ * @return an updated builder
*/
ChainBuilder withStep(ChainStep<File> step);
/**
* Actually consumes all the files supplied.
+ * @param sink sink that the entries will be sent to
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be written for other reasons
*/
void to(Sink<File> sink) throws IOException, ArchiveException;
}
/**
* Sets the source of files to be a directory.
+ * @param f the source directory
+ * @return a builder for the chain to be created and run
*/
public static ChainBuilder directory(File f) {
return source(new DirectoryBasedSource(f));
@@ -72,6 +87,8 @@ public class Archive {
/**
* Sets the source of files to process.
+ * @param source the source directory
+ * @return a builder for the chain to be created and run
*/
public static ChainBuilder source(Source<File> source) {
return new Builder(source);
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveEntrySource.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveEntrySource.java b/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveEntrySource.java
index f114eb6..402134f 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveEntrySource.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveEntrySource.java
@@ -29,6 +29,8 @@ public interface ArchiveEntrySource extends Source<ArchiveEntry> {
/**
* Provides a filter that can be used to skip entries the
* underlying source is unable to read the content of.
+ * @return filter that can be used to skip entries the underlying
+ * source is unable to read the content of
*/
Filter<ArchiveEntry> skipUnreadable();
}
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSinks.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSinks.java b/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSinks.java
index bfa410c..f00fc4f 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSinks.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSinks.java
@@ -36,17 +36,31 @@ import org.apache.commons.compress.archivers.zip.ZipArchiveOutputStream;
*/
public class ArchiveSinks {
/**
- * Uses {@link ArchiveFactory#createArchiveOutputStream}.
+ * Uses {@link ArchiveStreamFactory#createArchiveOutputStream}.
*
* <p>Will not support 7z.</p>
+ *
+ * @param format the archive format. This uses the same format as
+ * accepted by {@link ArchiveStreamFactory}.
+ * @param os the stream to write to.
+ * @return a sink that consumes the files
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public static Sink<File> forStream(String format, OutputStream os) throws IOException, ArchiveException {
return new FileToArchiveSink(new ArchiveStreamFactory().createArchiveOutputStream(format, os));
}
/**
- * Uses {@link ArchiveFactory#createArchiveOutputStream} unless
+ * Uses {@link ArchiveStreamFactory#createArchiveOutputStream} unless
* special handling for ZIP or 7z is required.
+ *
+ * @param format the archive format. This uses the same format as
+ * accepted by {@link ArchiveStreamFactory}.
+ * @param target the file to write to.
+ * @return a sink that consumes the files
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public static Sink<File> forFile(String format, File target) throws IOException, ArchiveException {
if (prefersSeekableByteChannel(format)) {
@@ -58,8 +72,15 @@ public class ArchiveSinks {
}
/**
- * Uses {@link ArchiveFactory#createArchiveOutputStream} unless
+ * Uses {@link ArchiveStreamFactory#createArchiveOutputStream} unless
* special handling for ZIP or 7z is required.
+ *
+ * @param format the archive format. This uses the same format as
+ * accepted by {@link ArchiveStreamFactory}.
+ * @param c the channel to write to.
+ * @return a sink that consumes the files
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be created for other reasons
*/
public static Sink<File> forChannel(String format, SeekableByteChannel c) throws IOException, ArchiveException {
if (!prefersSeekableByteChannel(format)) {
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSources.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSources.java b/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSources.java
index 39ca236..670eb2f 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSources.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/ArchiveSources.java
@@ -43,12 +43,29 @@ public class ArchiveSources {
* @since 1.17
*/
public interface PendingFormat {
+ /**
+ * Signals the format shall be detcted automatically.
+ * @return the configured source
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
+ */
ArchiveEntrySource detectFormat() throws IOException, ArchiveException;
+ /**
+ * Explicitly provides the expected format of the archive.
+ * @param format the archive format. This uses the same format as
+ * accepted by {@link ArchiveStreamFactory}.
+ * @return the configured source
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
+ */
ArchiveEntrySource withFormat(String format) throws IOException, ArchiveException;
}
/**
- * Uses {@link ArchiveFactory#createArchiveInputStream} unless special handling for ZIP or /z is required.
+ * Uses {@link ArchiveStreamFactory#createArchiveInputStream} unless special handling for ZIP or /z is required.
+ *
+ * @param f the file to read from
+ * @return a builder that needs to know the format
*/
public static PendingFormat forFile(final File f) {
return new PendingFormat() {
@@ -72,7 +89,14 @@ public class ArchiveSources {
}
/**
- * Uses {@link ArchiveFactory#createArchiveInputStream} unless special handling for ZIP or /z is required.
+ * Uses {@link ArchiveStreamFactory#createArchiveInputStream} unless special handling for ZIP or /z is required.
+ *
+ * @param format the archive format. This uses the same format as
+ * accepted by {@link ArchiveStreamFactory}.
+ * @param c the channel to read from
+ * @return the configured source
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the archive cannot be read for other reasons
*/
public static ArchiveEntrySource forChannel(String format, SeekableByteChannel c)
throws IOException, ArchiveException {
@@ -88,9 +112,12 @@ public class ArchiveSources {
}
/**
- * Uses {@link ArchiveFactory#createArchiveInputStream}.
+ * Uses {@link ArchiveStreamFactory#createArchiveInputStream}.
*
* <p>Will not support 7z.</p>
+ *
+ * @param in the stream to read from
+ * @return a builder that needs to know the format
*/
public static PendingFormat forStream(final InputStream in) {
return new PendingFormat() {
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/Chain.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/Chain.java b/src/main/java/org/apache/commons/compress/archivers/examples/Chain.java
index 9989395..86d2e1c 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/Chain.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/Chain.java
@@ -30,10 +30,22 @@ public class Chain<T> {
private final Iterator<ChainStep<T>> chain;
+ /**
+ * Instantiates a new chain.
+ *
+ * @param chain the steps to take in order.
+ */
public Chain(Iterator<ChainStep<T>> chain) {
this.chain = chain;
}
+ /**
+ * Invokes the next step of the chain.
+ *
+ * @param payload the payload to pass to the next step
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if an archive format related error occurs
+ */
public void next(ChainPayload<T> payload) throws IOException, ArchiveException {
if (chain.hasNext()) {
chain.next().process(payload, this);
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/ChainPayload.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/ChainPayload.java b/src/main/java/org/apache/commons/compress/archivers/examples/ChainPayload.java
index 82d96fb..11d8618 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/ChainPayload.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/ChainPayload.java
@@ -30,7 +30,7 @@ public class ChainPayload<T> {
private final Supplier<InputStream> input;
/**
* Constructs the payload.
- * @param T entry the actual payload
+ * @param entry entry the actual payload
* @param entryName the local name of the entry. This may - for
* example - be the file name relative to a directory.
* @param input supplies an input stream to the entry's
@@ -43,6 +43,8 @@ public class ChainPayload<T> {
}
/**
* Provides the real payload.
+ * @return the real playoad
+ *
*/
public T getEntry() {
return entry;
@@ -52,6 +54,8 @@ public class ChainPayload<T> {
*
* <p>This may - for example - be the file name relative to a
* directory.</p>
+ *
+ * @return local name of the entry
*/
public String getEntryName() {
return entryName;
@@ -61,6 +65,8 @@ public class ChainPayload<T> {
*
* <p>The supplier is not required to be callable more than
* once.</p>
+ *
+ * @return supplier of input
*/
public Supplier<InputStream> getInput() {
return input;
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/ChainStep.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/ChainStep.java b/src/main/java/org/apache/commons/compress/archivers/examples/ChainStep.java
index 9edb5aa..ee0e4b3 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/ChainStep.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/ChainStep.java
@@ -35,6 +35,8 @@ public interface ChainStep<T> {
*
* @param payload the payload.
* @param chain chain to return control to once processing is done.
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if an archive format related error occurs
*/
void process(ChainPayload<T> payload, Chain<T> chain) throws IOException, ArchiveException;
}
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/DirectoryBasedSource.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/DirectoryBasedSource.java b/src/main/java/org/apache/commons/compress/archivers/examples/DirectoryBasedSource.java
index 84d1a53..c6ca484 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/DirectoryBasedSource.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/DirectoryBasedSource.java
@@ -36,7 +36,10 @@ public class DirectoryBasedSource implements Source<File> {
private final File dir;
/**
+ * Sets up a directory as source.
+ *
* @param dir the directory to provide entries from.
+ * @throws IllegalArgumentException if dir doesn't exist or is not a directory
*/
public DirectoryBasedSource(File dir) {
if (!dir.isDirectory()) {
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/DirectorySink.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/DirectorySink.java b/src/main/java/org/apache/commons/compress/archivers/examples/DirectorySink.java
index 9cc1597..7a34858 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/DirectorySink.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/DirectorySink.java
@@ -36,7 +36,11 @@ public class DirectorySink extends Sink<ArchiveEntry> {
private final String dirPath;
/**
+ * Sets up a directory as sink.
+ *
* @param dir the directory to provide entries from.
+ * @throws IOException if the canonical path of the directory cannot be determined
+ * @throws IllegalArgumentException if dir doesn't exist or is not a directory
*/
public DirectorySink(File dir) throws IOException {
if (!dir.isDirectory()) {
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/Expand.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/Expand.java b/src/main/java/org/apache/commons/compress/archivers/examples/Expand.java
index 99e1f34..d6ece27 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/Expand.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/Expand.java
@@ -35,32 +35,45 @@ public class Expand {
public interface ChainBuilder {
/**
* Adds a filter to the chain.
+ * @param filter the filter to apply
+ * @return an updated builder
*/
ChainBuilder filter(Filter<ArchiveEntry> filter);
/**
* Adds a filter to the chain that filters out entries that cannot be read.
+ * @return an updated builder
*/
ChainBuilder skipUnreadable();
/**
* Adds a filter to the chain that suppresses all directory entries.
+ * @return an updated builder
*/
ChainBuilder skipDirectories();
/**
* Adds a transformer to the chain.
+ * @param transformer transformer to apply
+ * @return an updated builder
*/
ChainBuilder map(Transformer<ArchiveEntry> transformer);
/**
* Adds a generic step to the chain.
+ * @return an updated builder
+ * @param step step to perform
*/
ChainBuilder withStep(ChainStep<ArchiveEntry> step);
/**
* Actually consumes all the entries supplied.
+ * @param sink sink that the entries will be sent to
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if the source archive cannot be read for other reasons
*/
void to(Sink<ArchiveEntry> sink) throws IOException, ArchiveException;
}
/**
* Sets the source of entries to process.
+ * @param source the source
+ * @return a builder for the chain to be created and run
*/
public static ChainBuilder source(ArchiveEntrySource source) {
return new Builder(source);
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/FileToArchiveSink.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/FileToArchiveSink.java b/src/main/java/org/apache/commons/compress/archivers/examples/FileToArchiveSink.java
index c2c1f2b..7f9fa3d 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/FileToArchiveSink.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/FileToArchiveSink.java
@@ -36,6 +36,8 @@ public class FileToArchiveSink extends Sink<File> {
/**
* Wraps an ArchiveOutputStream.
+ *
+ * @param os the stream to write to
*/
public FileToArchiveSink(ArchiveOutputStream os) {
this.os = os;
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/Filter.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/Filter.java b/src/main/java/org/apache/commons/compress/archivers/examples/Filter.java
index 924864c..84e670c 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/Filter.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/Filter.java
@@ -29,7 +29,7 @@ public abstract class Filter<T> implements ChainStep<T> {
/**
* Decides whether to process an entry or not.
*
- * @param name of the entry
+ * @param entryName name of the entry
* @param entry the entry
* @return true if the entry shall be processed.
*/
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/Sink.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/Sink.java b/src/main/java/org/apache/commons/compress/archivers/examples/Sink.java
index eb81c1c..7e14369 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/Sink.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/Sink.java
@@ -29,6 +29,10 @@ import org.apache.commons.compress.archivers.ArchiveException;
public abstract class Sink<T> implements ChainStep<T>, Closeable {
/**
* Consume a single entry.
+ *
+ * @param payload the entry to consume
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if an archive format related error occurs
*/
public abstract void consume(ChainPayload<T> payload) throws IOException, ArchiveException;
@@ -36,6 +40,9 @@ public abstract class Sink<T> implements ChainStep<T>, Closeable {
* Is invoked once all entries have been processed.
*
* <p>This implementation is empty.
+ *
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if an archive format related error occurs
*/
public void finish() throws IOException, ArchiveException {
}
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/archivers/examples/Supplier.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/Supplier.java b/src/main/java/org/apache/commons/compress/archivers/examples/Supplier.java
index 6c73f91..aba6113 100644
--- a/src/main/java/org/apache/commons/compress/archivers/examples/Supplier.java
+++ b/src/main/java/org/apache/commons/compress/archivers/examples/Supplier.java
@@ -26,5 +26,12 @@ import org.apache.commons.compress.archivers.ArchiveException;
* @since 1.12
*/
public interface Supplier<T> {
+ /**
+ * Supplies the object.
+ *
+ * @throws IOException if an I/O error occurs
+ * @throws ArchiveException if an archive format related error occurs
+ * @return the asked for object
+ */
T get() throws IOException, ArchiveException;
}
http://git-wip-us.apache.org/repos/asf/commons-compress/blob/78cf6565/src/main/java/org/apache/commons/compress/utils/BitInputStream.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/compress/utils/BitInputStream.java b/src/main/java/org/apache/commons/compress/utils/BitInputStream.java
index 124e21f..8abff5f 100644
--- a/src/main/java/org/apache/commons/compress/utils/BitInputStream.java
+++ b/src/main/java/org/apache/commons/compress/utils/BitInputStream.java
@@ -130,6 +130,7 @@ public class BitInputStream implements Closeable {
*
* <p>This includes the bytes read to fill the current cache and
* not read as bits so far.</p>
+ * @return the number of bytes read from the underlying stream
* @since 1.17
*/
public long getBytesRead() {