Repository: commons-compress Updated Branches: refs/heads/master 78cf6565c -> 06c4b62ca
COMPRESS-118 add package level javdocs Project: http://git-wip-us.apache.org/repos/asf/commons-compress/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-compress/commit/06c4b62c Tree: http://git-wip-us.apache.org/repos/asf/commons-compress/tree/06c4b62c Diff: http://git-wip-us.apache.org/repos/asf/commons-compress/diff/06c4b62c Branch: refs/heads/master Commit: 06c4b62ca5e506cb066773444e7753712d6e807e Parents: 78cf656 Author: Stefan Bodewig <bode...@apache.org> Authored: Mon Apr 30 17:13:42 2018 +0200 Committer: Stefan Bodewig <bode...@apache.org> Committed: Mon Apr 30 17:13:42 2018 +0200 ---------------------------------------------------------------------- .../compress/archivers/examples/package.html | 92 ++++++++++++++++++++ 1 file changed, 92 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-compress/blob/06c4b62c/src/main/java/org/apache/commons/compress/archivers/examples/package.html ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/compress/archivers/examples/package.html b/src/main/java/org/apache/commons/compress/archivers/examples/package.html new file mode 100644 index 0000000..14e6c5a --- /dev/null +++ b/src/main/java/org/apache/commons/compress/archivers/examples/package.html @@ -0,0 +1,92 @@ +<html> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License 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. + +--> + <body> + <p>Contains examples code that is not guaranteed to provide a + stable API across releases of Commons Compress.</p> + + <p>The majority of this package is concerned with the archival of + the contents of a directory into a single archive or the expansion + of an archive's content into a local directory. Example CLI + programs exist with {@link + org.apache.commons.compress.archivers.examples.ArchiveCli}, {@link + org.apache.commons.compress.archivers.examples.ExpandCli} and + {@link + org.apache.commons.compress.archivers.examples.ListerCli}. As of + Commons Compress 1.17 this is the main class of the Commons + Compress jar, i.e. the class that is run when you start <code>java + -jar commons-compress.jar</code>.</p> + + <h2>Chains</h2> + + <p>The basic abstraction of the package is the {@link + org.apache.commons.compress.archivers.examples.Chain}, a chain of + {@link org.apache.commons.compress.archivers.examples.ChainStep}s + that are executed in order for each entry. Entries are supplied by + a {@link org.apache.commons.compress.archivers.examples.Source} + and finally consumed by a {@link + org.apache.commons.compress.archivers.examples.Sink}. While {@code + Sink}s are {@code ChainStep}s and must be the final step in a + {@code Chain}, {@code Source}s are not considered part of the + {@code Chain}.</p> + + <p>Special {@code ChainStep}s exist for filtering entries with + {@link org.apache.commons.compress.archivers.examples.Filter} or + transforming entries {@link + org.apache.commons.compress.archivers.examples.Transformer} as + they pass through the chain.</p> + + <h3>Archival and Expansion</h3> + + <p>A chain that takes files from the local file system and creates + an archive from that can be set up and run with the help of the + {@link org.apache.commons.compress.archivers.examples.Archive} + class. The most common source is {@link + org.apache.commons.compress.archivers.examples.DirectoryBasedSource} + which simply supplies all files contained within the directory + recursively. The {@link + org.apache.commons.compress.archivers.examples.ArchiveSinks} class + provides factory methods for the many ways that can bes used to + create archives to write to - all those factory methods end up + with creating instances of {@link + org.apache.commons.compress.archivers.examples.FileToArchiveSink} + or {@link + org.apache.commons.compress.archivers.examples.SevenZOutputFileSink} + under the covers.</p> + + <p>A chain that takes {@link + org.apache.commons.compress.archivers.ArchiveEntry}s from a source + and passes them to a sink can be set up and run with the help of + the {@link org.apache.commons.compress.archivers.examples.Expand} + class. The most common sink will be a {@link + org.apache.commons.compress.archivers.examples.DirectorySink} + which writes the entries to a local directory, but different sinks + are easy to imagine - and in fact {@code ListerCli} uses {@code + Expand} and simply provides a sink that just prints out the names + of the entries. Sources that read from archives can be created via + the factory methods in {@link + org.apache.commons.compress.archivers.examples.ArchiveSources} + which under the covers will create instances of {@link + org.apache.commons.compress.archivers.examples.StreamBasedArchiveEntrySource}, + {@link + org.apache.commons.compress.archivers.examples.SevenZArchiveEntrySource} + or {@link + org.apache.commons.compress.archivers.examples.ZipArchiveEntrySource}.</p> + </body> +</html>
