Package org.apache.commons.compress.archivers

Class ArchiveOutputStream<E extends ArchiveEntry>

java.lang.Object

java.io.OutputStream

java.io.FilterOutputStream

org.apache.commons.compress.archivers.ArchiveOutputStream<E>

Type Parameters:

E - The type of ArchiveEntry consumed.

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

Direct Known Subclasses:

ArArchiveOutputStream, CpioArchiveOutputStream, TarArchiveOutputStream, ZipArchiveOutputStream

public abstract class ArchiveOutputStream<E extends ArchiveEntry>
extends 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:
  • putArchiveEntry(ArchiveEntry) (writes entry header),
  • FilterOutputStream.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,
• close().

Field Summary

Fields inherited from class java.io.FilterOutputStream

out

Constructor Summary

Constructors

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

Method Summary

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(File inputFile, String entryName)	Creates an archive entry using the inputFile and entryName provided.
E	createArchiveEntry(Path inputPath, String entryName, 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.
int	getCount()	Deprecated. this method may yield wrong results for large archives, use #getBytesWritten instead
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.lang.Object

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

Constructor Details

ArchiveOutputStream

public ArchiveOutputStream()

Constructs a new instance without a backing OutputStream.

You must initialize this.out after construction.

ArchiveOutputStream

public ArchiveOutputStream(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 Details

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 IOException

Throws an IOException if this instance is already finished.

Throws:

IOException - if this instance is already finished.

Since:

1.27.0

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class FilterOutputStream

Throws:

IOException

closeArchiveEntry

public abstract void closeArchiveEntry()
                                throws IOException

Closes the archive entry, writing any trailer information that may be required.

Throws:

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(File inputFile,
 String entryName)
                              throws IOException

Creates an archive entry using the inputFile and entryName provided.

Parameters:

inputFile - the file to create the entry from

entryName - name to use for the entry

Returns:

the ArchiveEntry set up with details from the file

Throws:

IOException - if an I/O error occurs

createArchiveEntry

public E createArchiveEntry(Path inputPath,
 String entryName,
 LinkOption... options)
                     throws 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:

IOException - if an I/O error occurs

Since:

1.21

finish

public void finish()
            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 - 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

getCount

@Deprecated
public int getCount()

Deprecated.

this method may yield wrong results for large archives, use #getBytesWritten instead

Gets the current number of bytes written to this stream.

Returns:

the number of written bytes

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 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:

IOException - if an I/O error occurs

write

public void write(int b)
           throws 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 FilterOutputStream

Parameters:

b - The byte to be written.

Throws:

IOException - on error

checkOpen

protected void checkOpen()
                  throws IOException

Check to make sure that this stream has not been closed

Throws:

IOException - if the stream is already closed

Since:

1.27.0