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.archivers;
021
022import java.io.InputStream;
023import java.io.OutputStream;
024import java.util.Set;
025
026/**
027 * Creates Archive {@link ArchiveInputStream}s and {@link ArchiveOutputStream}s.
028 *
029 * @since 1.13
030 */
031public interface ArchiveStreamProvider {
032
033    /**
034     * Creates an archive input stream from an archiver name and an input stream.
035     *
036     * @param <I>          The {@link ArchiveInputStream} type.
037     * @param archiverName the archiver name, i.e. {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#AR},
038     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#ARJ},
039     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#ZIP},
040     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#TAR},
041     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#JAR},
042     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#CPIO},
043     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#DUMP} or
044     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#SEVEN_Z}
045     * @param inputStream  the input stream
046     * @param encoding     encoding name or null for the default
047     * @return the archive input stream
048     * @throws ArchiveException               if the archiver name is not known
049     * @throws StreamingNotSupportedException if the format cannot be read from a stream
050     * @throws IllegalArgumentException       if the archiver name or stream is null
051     */
052    <I extends ArchiveInputStream<? extends ArchiveEntry>> I createArchiveInputStream(String archiverName, InputStream inputStream, String encoding)
053            throws ArchiveException;
054
055    /**
056     * Creates an archive output stream from an archiver name and an output stream.
057     *
058     * @param <O>          The {@link ArchiveInputStream} type.
059     * @param archiverName the archiver name, i.e. {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#AR},
060     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#ZIP},
061     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#TAR},
062     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#JAR} or
063     *                     {@value org.apache.commons.compress.archivers.ArchiveStreamFactory#CPIO}
064     * @param outputStream the output stream
065     * @param encoding     encoding name or null for the default
066     * @return the archive output stream
067     * @throws ArchiveException               if the archiver name is not known
068     * @throws StreamingNotSupportedException if the format cannot be written to a stream
069     * @throws IllegalArgumentException       if the archiver name or stream is null
070     */
071    <O extends ArchiveOutputStream<? extends ArchiveEntry>> O createArchiveOutputStream(String archiverName, OutputStream outputStream, String encoding)
072            throws ArchiveException;
073
074    /**
075     * Gets all the input stream archive names for this provider
076     *
077     * @return all the input archive names for this provider
078     */
079    Set<String> getInputStreamArchiveNames();
080
081    /**
082     * Gets all the output stream archive names for this provider
083     *
084     * @return all the output archive names for this provider
085     */
086    Set<String> getOutputStreamArchiveNames();
087
088}