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