001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020package org.apache.commons.compress.compressors;
021
022import java.io.InputStream;
023import java.io.OutputStream;
024import java.util.Set;
025
026/**
027 * Creates Compressor {@link CompressorInputStream}s and
028 * {@link CompressorOutputStream}s.
029 *
030 * @since 1.13
031 */
032public interface CompressorStreamProvider {
033
034    /**
035     * Creates a compressor input stream from a compressor name and an input
036     * stream.
037     *
038     * @param name
039     *            of the compressor, i.e.
040     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#GZIP},
041     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#BZIP2},
042     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#XZ},
043     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#LZMA},
044     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#PACK200},
045     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#SNAPPY_RAW},
046     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#SNAPPY_FRAMED},
047     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#Z}
048     *            or
049     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#DEFLATE}
050     * @param in
051     *            the input stream
052     * @param decompressUntilEOF
053     *            if true, decompress until the end of the input; if false, stop
054     *            after the first stream and leave the input position to point
055     *            to the next byte after the stream. This setting applies to the
056     *            gzip, bzip2 and xz formats only.
057     * @return compressor input stream
058     * @throws CompressorException
059     *             if the compressor name is not known
060     * @throws IllegalArgumentException
061     *             if the name or input stream is null
062     */
063    CompressorInputStream createCompressorInputStream(final String name, final InputStream in,
064            final boolean decompressUntilEOF) throws CompressorException;
065
066    /**
067     * Creates a compressor output stream from an compressor name and an output
068     * stream.
069     *
070     * @param name
071     *            the compressor name, i.e.
072     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#GZIP},
073     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#BZIP2},
074     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#XZ},
075     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#PACK200}
076     *            or
077     *            {@value org.apache.commons.compress.compressors.CompressorStreamFactory#DEFLATE}
078     * @param out
079     *            the output stream
080     * @return the compressor output stream
081     * @throws CompressorException
082     *             if the archiver name is not known
083     * @throws IllegalArgumentException
084     *             if the archiver name or stream is null
085     */
086    CompressorOutputStream createCompressorOutputStream(final String name, final OutputStream out)
087            throws CompressorException;
088
089    /**
090     * Gets all the input stream compressor names for this provider
091     *
092     * @return all the input compressor names for this provider
093     */
094    Set<String> getInputStreamCompressorNames();
095
096    /**
097     * Gets all the output stream compressor names for this provider
098     *
099     * @return all the output compressor names for this provider
100     */
101    Set<String> getOutputStreamCompressorNames();
102
103}