ArchiveOutputStream.java

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

  21. import java.io.File;
  22. import java.io.FilterOutputStream;
  23. import java.io.IOException;
  24. import java.io.OutputStream;
  25. import java.nio.file.LinkOption;
  26. import java.nio.file.Path;

  28. /**
  29.  * Archive output stream implementations are expected to override the {@link #write(byte[], int, int)} method to improve performance. They should also override
  30.  * {@link #close()} to ensure that any necessary trailers are added.
  31.  *
  32.  * <p>
  33.  * The normal sequence of calls when working with ArchiveOutputStreams is:
  34.  * </p>
  35.  * <ul>
  36.  * <li>Create ArchiveOutputStream object,</li>
  37.  * <li>optionally write SFX header (Zip only),</li>
  38.  * <li>repeat as needed:
  39.  * <ul>
  40.  * <li>{@link #putArchiveEntry(ArchiveEntry)} (writes entry header),
  41.  * <li>{@link #write(byte[])} (writes entry data, as often as needed),
  42.  * <li>{@link #closeArchiveEntry()} (closes entry),
  43.  * </ul>
  44.  * </li>
  45.  * <li>{@link #finish()} (ends the addition of entries),</li>
  46.  * <li>optionally write additional data, provided format supports it,</li>
  47.  * <li>{@link #close()}.</li>
  48.  * </ul>
  49.  *
  50.  * @param <E> The type of {@link ArchiveEntry} consumed.
  51.  */
  52. public abstract class ArchiveOutputStream<E extends ArchiveEntry> extends FilterOutputStream {

  54.     static final int BYTE_MASK = 0xFF;

  56.     /** Temporary buffer used for the {@link #write(int)} method. */
  57.     private final byte[] oneByte = new byte[1];

  59.     /** Holds the number of bytes written to this stream. */
  60.     private long bytesWritten;

  62.     /**
  63.      * Whether this instance was successfully closed.
  64.      */
  65.     private boolean closed;

  67.     /**
  68.      * Whether this instance was successfully finished.
  69.      */
  70.     private boolean finished;

  72.     /**
  73.      * Constructs a new instance without a backing OutputStream.
  74.      * <p>
  75.      * You must initialize {@code this.out} after construction.
  76.      * </p>
  77.      */
  78.     public ArchiveOutputStream() {
  79.         super(null);
  80.     }

  82.     /**
  83.      * Constructs a new instance with the given backing OutputStream.
  84.      *
  85.      * @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
  86.      *            without an underlying stream.
  87.      * @since 1.27.0.
  88.      */
  89.     public ArchiveOutputStream(final OutputStream out) {
  90.         super(out);
  91.     }

  93.     /**
  94.      * Whether this stream is able to write the given entry.
  95.      *
  96.      * <p>
  97.      * Some archive formats support variants or details that are not supported (yet).
  98.      * </p>
  99.      *
  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.     }

  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.     }

  120.     @Override
  121.     public void close() throws IOException {
  122.         super.close();
  123.         closed = true;
  124.     }

  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;

  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.     }

  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.     }

  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;

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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;

  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.     }

  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. }
Created with JaCoCo 0.8.12.202403310830