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 <bode...@apache.org> Authored: Mon Apr 30 16:53:19 2018 +0200 Committer: Stefan Bodewig <bode...@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() {
