    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 */
    019package org.apache.commons.compress.archivers;
    020
    021import java.io.File;
    022import java.io.FilterOutputStream;
    023import java.io.IOException;
    024import java.io.OutputStream;
    025import java.nio.file.LinkOption;
    026import java.nio.file.Path;
    027
    028/**
    029 * Archive output stream implementations are expected to override the {@link #write(byte[], int, int)} method to improve performance. They should also override
    030 * {@link #close()} to ensure that any necessary trailers are added.
    031 *
    032 * <p>
    033 * The normal sequence of calls when working with ArchiveOutputStreams is:
    034 * </p>
    035 * <ul>
    036 * <li>Create ArchiveOutputStream object,</li>
    037 * <li>optionally write SFX header (Zip only),</li>
    038 * <li>repeat as needed:
    039 * <ul>
    040 * <li>{@link #putArchiveEntry(ArchiveEntry)} (writes entry header),
    041 * <li>{@link #write(byte[])} (writes entry data, as often as needed),
    042 * <li>{@link #closeArchiveEntry()} (closes entry),
    043 * </ul>
    044 * </li>
    045 * <li>{@link #finish()} (ends the addition of entries),</li>
    046 * <li>optionally write additional data, provided format supports it,</li>
    047 * <li>{@link #close()}.</li>
    048 * </ul>
    049 *
    050 * @param <E> The type of {@link ArchiveEntry} consumed.
    051 */
    052public abstract class ArchiveOutputStream<E extends ArchiveEntry> extends FilterOutputStream {
    053
    054    static final int BYTE_MASK = 0xFF;
    055
    056    /** Temporary buffer used for the {@link #write(int)} method. */
    057    private final byte[] oneByte = new byte[1];
    058
    059    /** Holds the number of bytes written to this stream. */
    060    private long bytesWritten;
    061
    062    /**
    063     * Whether this instance was successfully closed.
    064     */
    065    private boolean closed;
    066
    067    /**
    068     * Whether this instance was successfully finished.
    069     */
    070    private boolean finished;
    071
    072    /**
    073     * Constructs a new instance without a backing OutputStream.
    074     * <p>
    075     * You must initialize {@code this.out} after construction.
    076     * </p>
    077     */
    078    public ArchiveOutputStream() {
    079        super(null);
    080    }
    081
    082    /**
    083     * Constructs a new instance with the given backing OutputStream.
    084     *
    085     * @param out the underlying output stream to be assigned to the field {@code this.out} for later use, or {@code null} if this instance is to be created
    086     *            without an underlying stream.
    087     * @since 1.27.0.
    088     */
    089    public ArchiveOutputStream(final OutputStream out) {
    090        super(out);
    091    }
    092
    093    /**
    094     * Whether this stream is able to write the given entry.
    095     *
    096     * <p>
    097     * Some archive formats support variants or details that are not supported (yet).
    098     * </p>
    099     *
    100     * @param archiveEntry the entry to test
    101     * @return This implementation always returns true.
    102     * @since 1.1
    103     */
    104    public boolean canWriteEntryData(final ArchiveEntry archiveEntry) {
    105        return true;
    106    }
    107
    108    /**
    109     * Throws an {@link IOException} if this instance is already finished.
    110     *
    111     * @throws IOException if this instance is already finished.
    112     * @since 1.27.0
    113     */
    114    protected void checkFinished() throws IOException {
    115        if (isFinished()) {
    116            throw new IOException("Stream has already been finished.");
    117        }
    118    }
    119
    120    @Override
    121    public void close() throws IOException {
    122        super.close();
    123        closed = true;
    124    }
    125
    126    /**
    127     * Closes the archive entry, writing any trailer information that may be required.
    128     *
    129     * @throws IOException if an I/O error occurs
    130     */
    131    public abstract void closeArchiveEntry() throws IOException;
    132
    133    /**
    134     * Increments the counter of already written bytes. Doesn't increment if EOF has been hit ({@code written == -1}).
    135     *
    136     * @param written the number of bytes written
    137     */
    138    protected void count(final int written) {
    139        count((long) written);
    140    }
    141
    142    /**
    143     * Increments the counter of already written bytes. Doesn't increment if EOF has been hit ({@code written == -1}).
    144     *
    145     * @param written the number of bytes written
    146     * @since 1.1
    147     */
    148    protected void count(final long written) {
    149        if (written != -1) {
    150            bytesWritten += written;
    151        }
    152    }
    153
    154    /**
    155     * Creates an archive entry using the inputFile and entryName provided.
    156     *
    157     * @param inputFile the file to create the entry from
    158     * @param entryName name to use for the entry
    159     * @return the ArchiveEntry set up with details from the file
    160     *
    161     * @throws IOException if an I/O error occurs
    162     */
    163    public abstract E createArchiveEntry(File inputFile, String entryName) throws IOException;
    164
    165    /**
    166     * Creates an archive entry using the inputPath and entryName provided.
    167     * <p>
    168     * The default implementation calls simply delegates as:
    169     * </p>
    170     *
    171     * <pre>
    172     * return createArchiveEntry(inputFile.toFile(), entryName);
    173     * </pre>
    174     * <p>
    175     * Subclasses should override this method.
    176     * </p>
    177     *
    178     * @param inputPath the file to create the entry from
    179     * @param entryName name to use for the entry
    180     * @param options   options indicating how symbolic links are handled.
    181     * @return the ArchiveEntry set up with details from the file
    182     *
    183     * @throws IOException if an I/O error occurs
    184     * @since 1.21
    185     */
    186    public E createArchiveEntry(final Path inputPath, final String entryName, final LinkOption... options) throws IOException {
    187        return createArchiveEntry(inputPath.toFile(), entryName);
    188    }
    189
    190    /**
    191     * Finishes the addition of entries to this stream, without closing it. Additional data can be written, if the format supports it.
    192     *
    193     * @throws IOException Maybe thrown by subclasses if the user forgets to close the entry.
    194     */
    195    public void finish() throws IOException {
    196        finished = true;
    197    }
    198
    199    /**
    200     * Gets the current number of bytes written to this stream.
    201     *
    202     * @return the number of written bytes
    203     * @since 1.1
    204     */
    205    public long getBytesWritten() {
    206        return bytesWritten;
    207    }
    208
    209    /**
    210     * Gets the current number of bytes written to this stream.
    211     *
    212     * @return the number of written bytes
    213     * @deprecated this method may yield wrong results for large archives, use #getBytesWritten instead
    214     */
    215    @Deprecated
    216    public int getCount() {
    217        return (int) bytesWritten;
    218    }
    219
    220    /**
    221     * Tests whether this instance was successfully closed.
    222     *
    223     * @return whether this instance was successfully closed.
    224     * @since 1.27.0
    225     */
    226    protected boolean isClosed() {
    227        return closed;
    228    }
    229
    230    /**
    231     * Tests whether this instance was successfully finished.
    232     *
    233     * @return whether this instance was successfully finished.
    234     * @since 1.27.0
    235     */
    236    protected boolean isFinished() {
    237        return finished;
    238    }
    239
    240    /**
    241     * Writes the headers for an archive entry to the output stream. The caller must then write the content to the stream and call {@link #closeArchiveEntry()}
    242     * to complete the process.
    243     *
    244     * @param entry describes the entry
    245     * @throws IOException if an I/O error occurs
    246     */
    247    public abstract void putArchiveEntry(E entry) throws IOException;
    248
    249    /**
    250     * Writes a byte to the current archive entry.
    251     *
    252     * <p>
    253     * This method simply calls {@code write( byte[], 0, 1 )}.
    254     *
    255     * <p>
    256     * MUST be overridden if the {@link #write(byte[], int, int)} method is not overridden; may be overridden otherwise.
    257     *
    258     * @param b The byte to be written.
    259     * @throws IOException on error
    260     */
    261    @Override
    262    public void write(final int b) throws IOException {
    263        oneByte[0] = (byte) (b & BYTE_MASK);
    264        write(oneByte, 0, 1);
    265    }
    266
    267    /**
    268     * Check to make sure that this stream has not been closed
    269     *
    270     * @throws IOException if the stream is already closed
    271     * @since 1.27.0
    272     */
    273    protected void checkOpen() throws IOException {
    274        if (isClosed()) {
    275            throw new IOException("Stream closed");
    276        }
    277    }
    278}