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 *   https://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 {@link CompressorOutputStream}s.
028 *
029 * @since 1.13
030 */
031public interface CompressorStreamProvider {
032
033    /**
034     * Creates a compressor input stream from a compressor name and an input stream.
035     *
036     * @param name               of the compressor, i.e. {@value org.apache.commons.compress.compressors.CompressorStreamFactory#GZIP},
037     *                           {@value org.apache.commons.compress.compressors.CompressorStreamFactory#BZIP2},
038     *                           {@value org.apache.commons.compress.compressors.CompressorStreamFactory#XZ},
039     *                           {@value org.apache.commons.compress.compressors.CompressorStreamFactory#LZMA},
040     *                           {@value org.apache.commons.compress.compressors.CompressorStreamFactory#PACK200},
041     *                           {@value org.apache.commons.compress.compressors.CompressorStreamFactory#SNAPPY_RAW},
042     *                           {@value org.apache.commons.compress.compressors.CompressorStreamFactory#SNAPPY_FRAMED},
043     *                           {@value org.apache.commons.compress.compressors.CompressorStreamFactory#Z} or
044     *                           {@value org.apache.commons.compress.compressors.CompressorStreamFactory#DEFLATE}
045     * @param in                 the input stream
046     * @param decompressUntilEof if true, decompress until the end of the input; if false, stop after the first stream and leave the input position to point to
047     *                           the next byte after the stream. This setting applies to the gzip, bzip2 and XZ formats only.
048     * @return compressor input stream
049     * @throws CompressorException      if the compressor name is not known
050     * @throws IllegalArgumentException if the name or input stream is null
051     */
052    CompressorInputStream createCompressorInputStream(String name, InputStream in, boolean decompressUntilEof) throws CompressorException;
053
054    /**
055     * Creates a compressor output stream from a compressor name and an output stream.
056     *
057     * @param <T> The underlying output stream.
058     * @param name the compressor name, i.e. {@value org.apache.commons.compress.compressors.CompressorStreamFactory#GZIP},
059     *             {@value org.apache.commons.compress.compressors.CompressorStreamFactory#BZIP2},
060     *             {@value org.apache.commons.compress.compressors.CompressorStreamFactory#XZ},
061     *             {@value org.apache.commons.compress.compressors.CompressorStreamFactory#PACK200} or
062     *             {@value org.apache.commons.compress.compressors.CompressorStreamFactory#DEFLATE}
063     * @param out  the output stream
064     * @return the compressor output stream
065     * @throws CompressorException      if the archiver name is not known
066     * @throws IllegalArgumentException if the archiver name or stream is null
067     */
068    <T extends OutputStream> CompressorOutputStream<T> createCompressorOutputStream(String name, T out) throws CompressorException;
069
070    /**
071     * Gets all the input stream compressor names for this provider
072     *
073     * @return all the input compressor names for this provider
074     */
075    Set<String> getInputStreamCompressorNames();
076
077    /**
078     * Gets all the output stream compressor names for this provider
079     *
080     * @return all the output compressor names for this provider
081     */
082    Set<String> getOutputStreamCompressorNames();
083
084}