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