/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.commons.compress.archivers;

import java.io.File;
import java.io.IOException;
import java.io.OutputStream;

Archive output stream implementations are expected to override the OutputStream.write(byte[], int, int) method to improve performance. They should also override OutputStream.close() to ensure that any necessary trailers are added. 
The normal sequence of calls when working with ArchiveOutputStreams is:

  
Create ArchiveOutputStream object,
  
optionally write SFX header (Zip only),
  
repeat as needed:
    

      
putArchiveEntry(ArchiveEntry) (writes entry header), 
OutputStream.write(byte[]) (writes entry data, as often as needed), 
closeArchiveEntry() (closes entry), 
  
  
 finish() (ends the addition of entries),
  
 optionally write additional data, provided format supports it,
  
OutputStream.close().

/**
 * Archive output stream implementations are expected to override the
 * {@link #write(byte[], int, int)} method to improve performance.
 * They should also override {@link #close()} to ensure that any necessary
 * trailers are added.
 *
 * <p>The normal sequence of calls when working with ArchiveOutputStreams is:</p>
 * <ul>
 *   <li>Create ArchiveOutputStream object,</li>
 *   <li>optionally write SFX header (Zip only),</li>
 *   <li>repeat as needed:
 *     <ul>
 *       <li>{@link #putArchiveEntry(ArchiveEntry)} (writes entry header),
 *       <li>{@link #write(byte[])} (writes entry data, as often as needed),
 *       <li>{@link #closeArchiveEntry()} (closes entry),
 *     </ul>
 *   </li>
 *   <li> {@link #finish()} (ends the addition of entries),</li>
 *   <li> optionally write additional data, provided format supports it,</li>
 *   <li>{@link #close()}.</li>
 * </ul>
 */
public abstract class ArchiveOutputStream extends OutputStream {

    
Temporary buffer used for the write(int) method /** Temporary buffer used for the {@link #write(int)} method */
    private final byte[] oneByte = new byte[1];
    static final int BYTE_MASK = 0xFF;

    
holds the number of bytes written to this stream /** holds the number of bytes written to this stream */
    private long bytesWritten = 0;
    // Methods specific to ArchiveOutputStream

    
Writes the headers for an archive entry to the output stream. The caller must then write the content to the stream and call closeArchiveEntry() to complete the process. 
Params:
entry – describes the entry
Throws:
IOException – if an I/O error occurs/**
     * 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()} to complete the process.
     *
     * @param entry describes the entry
     * @throws IOException if an I/O error occurs
     */
    public abstract void putArchiveEntry(ArchiveEntry entry) throws IOException;

    
Closes the archive entry, writing any trailer information that may
be required.
Throws:
IOException – if an I/O error occurs/**
     * Closes the archive entry, writing any trailer information that may
     * be required.
     * @throws IOException if an I/O error occurs
     */
    public abstract void closeArchiveEntry() throws IOException;

    
Finishes the addition of entries to this stream, without closing it.
Additional data can be written, if the format supports it.
Throws:
IOException – if the user forgets to close the entry./**
     * Finishes the addition of entries to this stream, without closing it.
     * Additional data can be written, if the format supports it.
     *
     * @throws IOException if the user forgets to close the entry.
     */
    public abstract void finish() throws IOException;

    
Create an archive entry using the inputFile and entryName provided.
Params:
inputFile – the file to create the entry from
entryName – name to use for the entry
Throws:
IOException – if an I/O error occurs
Returns:
the ArchiveEntry set up with details from the file/**
     * Create an archive entry using the inputFile and entryName provided.
     *
     * @param inputFile the file to create the entry from
     * @param entryName name to use for the entry
     * @return the ArchiveEntry set up with details from the file
     *
     * @throws IOException if an I/O error occurs
     */
    public abstract ArchiveEntry createArchiveEntry(File inputFile, String entryName) throws IOException;

    // Generic implementations of OutputStream methods that may be useful to sub-classes

    
Writes a byte to the current archive entry.
This method simply calls write( byte[], 0, 1 ). 
MUST be overridden if the OutputStream.write(byte[], int, int) method is not overridden; may be overridden otherwise. 
Params:
b – The byte to be written.
Throws:
IOException – on error/**
     * Writes a byte to the current archive entry.
     *
     * <p>This method simply calls {@code write( byte[], 0, 1 )}.
     *
     * <p>MUST be overridden if the {@link #write(byte[], int, int)} method
     * is not overridden; may be overridden otherwise.
     *
     * @param b The byte to be written.
     * @throws IOException on error
     */
    @Override
    public void write(final int b) throws IOException {
        oneByte[0] = (byte) (b & BYTE_MASK);
        write(oneByte, 0, 1);
    }

    
Increments the counter of already written bytes. Doesn't increment if EOF has been hit (written == -1). 
Params:
written – the number of bytes written/**
     * Increments the counter of already written bytes.
     * Doesn't increment if EOF has been hit ({@code written == -1}).
     *
     * @param written the number of bytes written
     */
    protected void count(final int written) {
        count((long) written);
    }

    
Increments the counter of already written bytes. Doesn't increment if EOF has been hit (written == -1). 
Params:
written – the number of bytes written
Since:
1.1/**
     * Increments the counter of already written bytes.
     * Doesn't increment if EOF has been hit ({@code written == -1}).
     *
     * @param written the number of bytes written
     * @since 1.1
     */
    protected void count(final long written) {
        if (written != -1) {
            bytesWritten = bytesWritten + written;
        }
    }

    
Returns the current number of bytes written to this stream.
Returns:
the number of written bytes
Deprecated:
this method may yield wrong results for large
archives, use #getBytesWritten instead/**
     * Returns the current number of bytes written to this stream.
     * @return the number of written bytes
     * @deprecated this method may yield wrong results for large
     * archives, use #getBytesWritten instead
     */
    @Deprecated
    public int getCount() {
        return (int) bytesWritten;
    }

    
Returns the current number of bytes written to this stream.
Returns:
the number of written bytes
Since:
1.1/**
     * Returns the current number of bytes written to this stream.
     * @return the number of written bytes
     * @since 1.1
     */
    public long getBytesWritten() {
        return bytesWritten;
    }

    
Whether this stream is able to write the given entry.
Some archive formats support variants or details that are
not supported (yet).
Params:
archiveEntry – 
           the entry to test
Returns:
This implementation always returns true.
Since:
1.1/**
     * Whether this stream is able to write the given entry.
     *
     * <p>Some archive formats support variants or details that are
     * not supported (yet).</p>
     *
     * @param archiveEntry
     *            the entry to test
     * @return This implementation always returns true.
     * @since 1.1
     */
    public boolean canWriteEntryData(final ArchiveEntry archiveEntry) {
        return true;
    }
}