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