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}