    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.IOException;
    023import java.io.OutputStream;
    024import java.nio.file.LinkOption;
    025import java.nio.file.Path;
    026
    027/**
    028 * Archive output stream implementations are expected to override the
    029 * {@link #write(byte[], int, int)} method to improve performance.
    030 * They should also override {@link #close()} to ensure that any necessary
    031 * trailers are added.
    032 *
    033 * <p>The normal sequence of calls when working with ArchiveOutputStreams is:</p>
    034 * <ul>
    035 *   <li>Create ArchiveOutputStream object,</li>
    036 *   <li>optionally write SFX header (Zip only),</li>
    037 *   <li>repeat as needed:
    038 *     <ul>
    039 *       <li>{@link #putArchiveEntry(ArchiveEntry)} (writes entry header),
    040 *       <li>{@link #write(byte[])} (writes entry data, as often as needed),
    041 *       <li>{@link #closeArchiveEntry()} (closes entry),
    042 *     </ul>
    043 *   </li>
    044 *   <li> {@link #finish()} (ends the addition of entries),</li>
    045 *   <li> optionally write additional data, provided format supports it,</li>
    046 *   <li>{@link #close()}.</li>
    047 * </ul>
    048 * @param <E> The type of {@link ArchiveEntry} consumed.
    049 */
    050public abstract class ArchiveOutputStream<E extends ArchiveEntry> extends OutputStream {
    051
    052    static final int BYTE_MASK = 0xFF;
    053
    054    /** Temporary buffer used for the {@link #write(int)} method. */
    055    private final byte[] oneByte = new byte[1];
    056
    057    /** holds the number of bytes written to this stream. */
    058    private long bytesWritten;
    059
    060    /**
    061     * Whether this stream is able to write the given entry.
    062     *
    063     * <p>Some archive formats support variants or details that are
    064     * not supported (yet).</p>
    065     *
    066     * @param archiveEntry
    067     *            the entry to test
    068     * @return This implementation always returns true.
    069     * @since 1.1
    070     */
    071    public boolean canWriteEntryData(final ArchiveEntry archiveEntry) {
    072        return true;
    073    }
    074
    075    /**
    076     * Closes the archive entry, writing any trailer information that may
    077     * be required.
    078     * @throws IOException if an I/O error occurs
    079     */
    080    public abstract void closeArchiveEntry() throws IOException;
    081
    082    /**
    083     * Increments the counter of already written bytes.
    084     * Doesn't increment if EOF has been hit ({@code written == -1}).
    085     *
    086     * @param written the number of bytes written
    087     */
    088    protected void count(final int written) {
    089        count((long) written);
    090    }
    091
    092    /**
    093     * Increments the counter of already written bytes.
    094     * Doesn't increment if EOF has been hit ({@code written == -1}).
    095     *
    096     * @param written the number of bytes written
    097     * @since 1.1
    098     */
    099    protected void count(final long written) {
    100        if (written != -1) {
    101            bytesWritten = bytesWritten + written;
    102        }
    103    }
    104
    105    /**
    106     * Creates an archive entry using the inputFile and entryName provided.
    107     *
    108     * @param inputFile the file to create the entry from
    109     * @param entryName name to use for the entry
    110     * @return the ArchiveEntry set up with details from the file
    111     *
    112     * @throws IOException if an I/O error occurs
    113     */
    114    public abstract E createArchiveEntry(File inputFile, String entryName) throws IOException;
    115
    116    /**
    117     * Creates an archive entry using the inputPath and entryName provided.
    118     * <p>
    119     * The default implementation calls simply delegates as:
    120     * </p>
    121     * <pre>return createArchiveEntry(inputFile.toFile(), entryName);</pre>
    122     * <p>
    123     * Subclasses should override this method.
    124     * </p>
    125     *
    126     * @param inputPath the file to create the entry from
    127     * @param entryName name to use for the entry
    128     * @param options options indicating how symbolic links are handled.
    129     * @return the ArchiveEntry set up with details from the file
    130     *
    131     * @throws IOException if an I/O error occurs
    132     * @since 1.21
    133     */
    134    public E createArchiveEntry(final Path inputPath, final String entryName, final LinkOption... options) throws IOException {
    135        return createArchiveEntry(inputPath.toFile(), entryName);
    136    }
    137
    138    /**
    139     * Finishes the addition of entries to this stream, without closing it.
    140     * Additional data can be written, if the format supports it.
    141     *
    142     * @throws IOException if the user forgets to close the entry.
    143     */
    144    public abstract void finish() throws IOException;
    145
    146    /**
    147     * Gets the current number of bytes written to this stream.
    148     *
    149     * @return the number of written bytes
    150     * @since 1.1
    151     */
    152    public long getBytesWritten() {
    153        return bytesWritten;
    154    }
    155
    156    /**
    157     * Gets the current number of bytes written to this stream.
    158     *
    159     * @return the number of written bytes
    160     * @deprecated this method may yield wrong results for large
    161     * archives, use #getBytesWritten instead
    162     */
    163    @Deprecated
    164    public int getCount() {
    165        return (int) bytesWritten;
    166    }
    167
    168    /**
    169     * Writes the headers for an archive entry to the output stream.
    170     * The caller must then write the content to the stream and call
    171     * {@link #closeArchiveEntry()} to complete the process.
    172     *
    173     * @param entry describes the entry
    174     * @throws IOException if an I/O error occurs
    175     */
    176    public abstract void putArchiveEntry(E entry) throws IOException;
    177
    178    /**
    179     * Writes a byte to the current archive entry.
    180     *
    181     * <p>This method simply calls {@code write( byte[], 0, 1 )}.
    182     *
    183     * <p>MUST be overridden if the {@link #write(byte[], int, int)} method
    184     * is not overridden; may be overridden otherwise.
    185     *
    186     * @param b The byte to be written.
    187     * @throws IOException on error
    188     */
    189    @Override
    190    public void write(final int b) throws IOException {
    191        oneByte[0] = (byte) (b & BYTE_MASK);
    192        write(oneByte, 0, 1);
    193    }
    194}