Module kala.compress.base
Package kala.compress.archivers

Class ArchiveOutputStream<E extends ArchiveEntry>

  • Type Parameters:
    E - The type of ArchiveEntry consumed.
    All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable
    Direct Known Subclasses:
    ArArchiveOutputStream, CpioArchiveOutputStream, TarArchiveOutputStream, ZipArchiveOutputStream
    public abstract class ArchiveOutputStream<E extends ArchiveEntry>
extends java.io.FilterOutputStream
    Archive output stream implementations are expected to override the FilterOutputStream.write(byte[], int, int) method to improve performance. They should also override 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:
    • finish() (ends the addition of entries),
    • optionally write additional data, provided format supports it,
    • close().

    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) static int BYTE_MASK  
      private long bytesWritten
      Holds the number of bytes written to this stream.
      private boolean closed
      Whether this instance was successfully closed.
      private boolean finished
      Whether this instance was successfully finished.
      private byte[] oneByte
      Temporary buffer used for the write(int) method.

      • Fields inherited from class java.io.FilterOutputStream

        out

    • Constructor Summary

      Constructors 
      Constructor Description
      ArchiveOutputStream()
      Constructs a new instance without a backing OutputStream.
      ArchiveOutputStream​(java.io.OutputStream out)
      Constructs a new instance with the given backing OutputStream.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      boolean canWriteEntryData​(ArchiveEntry archiveEntry)
      Whether this stream is able to write the given entry.
      protected void checkFinished()
      Throws an IOException if this instance is already finished.
      protected void checkOpen()
      Check to make sure that this stream has not been closed
      void close()  
      abstract void closeArchiveEntry()
      Closes the archive entry, writing any trailer information that may be required.
      protected void count​(int written)
      Increments the counter of already written bytes.
      protected void count​(long written)
      Increments the counter of already written bytes.
      abstract E createArchiveEntry​(java.nio.file.Path inputPath, java.lang.String entryName, java.nio.file.LinkOption... options)
      Creates an archive entry using the inputPath and entryName provided.
      void finish()
      Finishes the addition of entries to this stream, without closing it.
      long getBytesWritten()
      Gets the current number of bytes written to this stream.
      protected boolean isClosed()
      Tests whether this instance was successfully closed.
      protected boolean isFinished()
      Tests whether this instance was successfully finished.
      abstract void putArchiveEntry​(E entry)
      Writes the headers for an archive entry to the output stream.
      void write​(int b)
      Writes a byte to the current archive entry.

      • Methods inherited from class java.io.FilterOutputStream

        flush, write, write

      • Methods inherited from class java.io.OutputStream

        nullOutputStream

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • oneByte

        private final byte[] oneByte
        Temporary buffer used for the write(int) method.

      • bytesWritten

        private long bytesWritten
        Holds the number of bytes written to this stream.

      • closed

        private boolean closed
        Whether this instance was successfully closed.

      • finished

        private boolean finished
        Whether this instance was successfully finished.

    • Constructor Detail

      • ArchiveOutputStream

        public ArchiveOutputStream()
        Constructs a new instance without a backing OutputStream.

        You must initialize this.out after construction.

      • ArchiveOutputStream

        public ArchiveOutputStream​(java.io.OutputStream out)
        Constructs a new instance with the given backing OutputStream.
        Parameters:
        out - the underlying output stream to be assigned to the field this.out for later use, or null if this instance is to be created without an underlying stream.
        Since:
        1.27.0.

    • Method Detail

      • canWriteEntryData

        public boolean canWriteEntryData​(ArchiveEntry archiveEntry)
        Whether this stream is able to write the given entry.

        Some archive formats support variants or details that are not supported (yet).

        Parameters:
        archiveEntry - the entry to test
        Returns:
        This implementation always returns true.
        Since:
        1.1

      • checkFinished

        protected void checkFinished()
                      throws java.io.IOException
        Throws an IOException if this instance is already finished.
        Throws:
        java.io.IOException - if this instance is already finished.
        Since:
        1.27.0

      • checkOpen

        protected void checkOpen()
                  throws java.io.IOException
        Check to make sure that this stream has not been closed
        Throws:
        java.io.IOException - if the stream is already closed
        Since:
        1.27.0

      • close

        public void close()
           throws java.io.IOException
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.FilterOutputStream
        Throws:
        java.io.IOException

      • closeArchiveEntry

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

      • count

        protected void count​(int written)
        Increments the counter of already written bytes. Doesn't increment if EOF has been hit (written == -1).
        Parameters:
        written - the number of bytes written

      • count

        protected void count​(long written)
        Increments the counter of already written bytes. Doesn't increment if EOF has been hit (written == -1).
        Parameters:
        written - the number of bytes written
        Since:
        1.1

      • createArchiveEntry

        public abstract E createArchiveEntry​(java.nio.file.Path inputPath,
                                     java.lang.String entryName,
                                     java.nio.file.LinkOption... options)
                              throws java.io.IOException
        Creates an archive entry using the inputPath and entryName provided.

        The default implementation calls simply delegates as: 

         return createArchiveEntry(inputFile.toFile(), entryName);

        Subclasses should override this method.

        Parameters:
        inputPath - the file to create the entry from
        entryName - name to use for the entry
        options - options indicating how symbolic links are handled.
        Returns:
        the ArchiveEntry set up with details from the file
        Throws:
        java.io.IOException - if an I/O error occurs
        Since:
        1.21

      • finish

        public void finish()
            throws java.io.IOException
        Finishes the addition of entries to this stream, without closing it. Additional data can be written, if the format supports it.
        Throws:
        java.io.IOException - Maybe thrown by subclasses if the user forgets to close the entry.

      • getBytesWritten

        public long getBytesWritten()
        Gets the current number of bytes written to this stream.
        Returns:
        the number of written bytes
        Since:
        1.1

      • isClosed

        protected boolean isClosed()
        Tests whether this instance was successfully closed.
        Returns:
        whether this instance was successfully closed.
        Since:
        1.27.0

      • isFinished

        protected boolean isFinished()
        Tests whether this instance was successfully finished.
        Returns:
        whether this instance was successfully finished.
        Since:
        1.27.0

      • putArchiveEntry

        public abstract void putArchiveEntry​(E entry)
                              throws java.io.IOException
        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.
        Parameters:
        entry - describes the entry
        Throws:
        java.io.IOException - if an I/O error occurs

      • write

        public void write​(int b)
           throws java.io.IOException
        Writes a byte to the current archive entry.

        This method simply calls write( byte[], 0, 1 ).

        MUST be overridden if the FilterOutputStream.write(byte[], int, int) method is not overridden; may be overridden otherwise.

        Overrides:
        write in class java.io.FilterOutputStream
        Parameters:
        b - The byte to be written.
        Throws:
        java.io.IOException - on error