FileDocCategorySizeDatePackage
TarOutputStream.javaAPI DocApache Ant 1.7012165Wed Dec 13 06:16:18 GMT 2006org.apache.tools.tar

TarOutputStream

public class TarOutputStream extends FilterOutputStream
The TarOutputStream writes a UNIX tar archive as an OutputStream. Methods are provided to put entries, and then write their contents by writing to this stream using write().

Fields Summary
public static final int
LONGFILE_ERROR
Fail if a long file name is required in the archive.
public static final int
LONGFILE_TRUNCATE
Long paths will be truncated in the archive.
public static final int
LONGFILE_GNU
GNU tar extensions are used to store long file names in the archive.
protected boolean
debug
protected long
currSize
protected String
currName
protected long
currBytes
protected byte[]
oneBuf
protected byte[]
recordBuf
protected int
assemLen
protected byte[]
assemBuf
protected TarBuffer
buffer
protected int
longFileMode
private boolean
closed
Constructors Summary
public TarOutputStream(OutputStream os)
Constructor for TarInputStream.

param
os the output stream to use


                   
       
        this(os, TarBuffer.DEFAULT_BLKSIZE, TarBuffer.DEFAULT_RCDSIZE);
public TarOutputStream(OutputStream os, int blockSize)
Constructor for TarInputStream.

param
os the output stream to use
param
blockSize the block size to use

        this(os, blockSize, TarBuffer.DEFAULT_RCDSIZE);
public TarOutputStream(OutputStream os, int blockSize, int recordSize)
Constructor for TarInputStream.

param
os the output stream to use
param
blockSize the block size to use
param
recordSize the record size to use

        super(os);

        this.buffer = new TarBuffer(os, blockSize, recordSize);
        this.debug = false;
        this.assemLen = 0;
        this.assemBuf = new byte[recordSize];
        this.recordBuf = new byte[recordSize];
        this.oneBuf = new byte[1];
Methods Summary
public voidclose()
Ends the TAR archive and closes the underlying OutputStream. This means that finish() is called followed by calling the TarBuffer's close().

throws
IOException on error

        if (!closed) {
            this.finish();
            this.buffer.close();
            out.close();
            closed = true;
        }
public voidcloseEntry()
Close an entry. This method MUST be called for all file entries that contain data. The reason is that we must buffer data written to the stream in order to satisfy the buffer's record based writes. Thus, there may be data fragments still being assembled that must be written to the output stream before this entry is closed and the next entry written.

throws
IOException on error

        if (this.assemLen > 0) {
            for (int i = this.assemLen; i < this.assemBuf.length; ++i) {
                this.assemBuf[i] = 0;
            }

            this.buffer.writeRecord(this.assemBuf);

            this.currBytes += this.assemLen;
            this.assemLen = 0;
        }

        if (this.currBytes < this.currSize) {
            throw new IOException("entry '" + currName + "' closed at '"
                                  + this.currBytes
                                  + "' before the '" + this.currSize
                                  + "' bytes specified in the header were written");
        }
public voidfinish()
Ends the TAR archive without closing the underlying OutputStream. The result is that the two EOF records of nulls are written.

throws
IOException on error

        // See Bugzilla 28776 for a discussion on this
        // http://issues.apache.org/bugzilla/show_bug.cgi?id=28776
        this.writeEOFRecord();
        this.writeEOFRecord();
public intgetRecordSize()
Get the record size being used by this stream's TarBuffer.

return
The TarBuffer record size.

        return this.buffer.getRecordSize();
public voidputNextEntry(TarEntry entry)
Put an entry on the output stream. This writes the entry's header record and positions the output stream for writing the contents of the entry. Once this method is called, the stream is ready for calls to write() to write the entry's contents. Once the contents are written, closeEntry() MUST be called to ensure that all buffered data is completely written to the output stream.

param
entry The TarEntry to be written to the archive.
throws
IOException on error

        if (entry.getName().length() >= TarConstants.NAMELEN) {

            if (longFileMode == LONGFILE_GNU) {
                // create a TarEntry for the LongLink, the contents
                // of which are the entry's name
                TarEntry longLinkEntry = new TarEntry(TarConstants.GNU_LONGLINK,
                                                      TarConstants.LF_GNUTYPE_LONGNAME);

                longLinkEntry.setSize(entry.getName().length() + 1);
                putNextEntry(longLinkEntry);
                write(entry.getName().getBytes());
                write(0);
                closeEntry();
            } else if (longFileMode != LONGFILE_TRUNCATE) {
                throw new RuntimeException("file name '" + entry.getName()
                                             + "' is too long ( > "
                                             + TarConstants.NAMELEN + " bytes)");
            }
        }

        entry.writeEntryHeader(this.recordBuf);
        this.buffer.writeRecord(this.recordBuf);

        this.currBytes = 0;

        if (entry.isDirectory()) {
            this.currSize = 0;
        } else {
            this.currSize = entry.getSize();
        }
        currName = entry.getName();
public voidsetBufferDebug(boolean debug)
Sets the debugging flag in this stream's TarBuffer.

param
debug True to turn on debugging.

        this.buffer.setDebug(debug);
public voidsetDebug(boolean debugF)
Sets the debugging flag.

param
debugF True to turn on debugging.

        this.debug = debugF;
public voidsetLongFileMode(int longFileMode)
Set the long file mode. This can be LONGFILE_ERROR(0), LONGFILE_TRUNCATE(1) or LONGFILE_GNU(2). This specifies the treatment of long file names (names >= TarConstants.NAMELEN). Default is LONGFILE_ERROR.

param
longFileMode the mode to use

        this.longFileMode = longFileMode;
public voidwrite(int b)
Writes a byte to the current tar archive entry. This method simply calls read( byte[], int, int ).

param
b The byte written.
throws
IOException on error

        this.oneBuf[0] = (byte) b;

        this.write(this.oneBuf, 0, 1);
public voidwrite(byte[] wBuf)
Writes bytes to the current tar archive entry. This method simply calls write( byte[], int, int ).

param
wBuf The buffer to write to the archive.
throws
IOException on error

        this.write(wBuf, 0, wBuf.length);
public voidwrite(byte[] wBuf, int wOffset, int numToWrite)
Writes bytes to the current tar archive entry. This method is aware of the current entry and will throw an exception if you attempt to write bytes past the length specified for the current entry. The method is also (painfully) aware of the record buffering required by TarBuffer, and manages buffers that are not a multiple of recordsize in length, including assembling records from small buffers.

param
wBuf The buffer to write to the archive.
param
wOffset The offset in the buffer from which to get bytes.
param
numToWrite The number of bytes to write.
throws
IOException on error

        if ((this.currBytes + numToWrite) > this.currSize) {
            throw new IOException("request to write '" + numToWrite
                                  + "' bytes exceeds size in header of '"
                                  + this.currSize + "' bytes for entry '"
                                  + currName + "'");

            //
            // We have to deal with assembly!!!
            // The programmer can be writing little 32 byte chunks for all
            // we know, and we must assemble complete records for writing.
            // REVIEW Maybe this should be in TarBuffer? Could that help to
            // eliminate some of the buffer copying.
            //
        }

        if (this.assemLen > 0) {
            if ((this.assemLen + numToWrite) >= this.recordBuf.length) {
                int aLen = this.recordBuf.length - this.assemLen;

                System.arraycopy(this.assemBuf, 0, this.recordBuf, 0,
                                 this.assemLen);
                System.arraycopy(wBuf, wOffset, this.recordBuf,
                                 this.assemLen, aLen);
                this.buffer.writeRecord(this.recordBuf);

                this.currBytes += this.recordBuf.length;
                wOffset += aLen;
                numToWrite -= aLen;
                this.assemLen = 0;
            } else {
                System.arraycopy(wBuf, wOffset, this.assemBuf, this.assemLen,
                                 numToWrite);

                wOffset += numToWrite;
                this.assemLen += numToWrite;
                numToWrite -= numToWrite;
            }
        }

        //
        // When we get here we have EITHER:
        // o An empty "assemble" buffer.
        // o No bytes to write (numToWrite == 0)
        //
        while (numToWrite > 0) {
            if (numToWrite < this.recordBuf.length) {
                System.arraycopy(wBuf, wOffset, this.assemBuf, this.assemLen,
                                 numToWrite);

                this.assemLen += numToWrite;

                break;
            }

            this.buffer.writeRecord(wBuf, wOffset);

            int num = this.recordBuf.length;

            this.currBytes += num;
            numToWrite -= num;
            wOffset += num;
        }
private voidwriteEOFRecord()
Write an EOF (end of archive) record to the tar archive. An EOF record consists of a record of all zeros.

        for (int i = 0; i < this.recordBuf.length; ++i) {
            this.recordBuf[i] = 0;
        }

        this.buffer.writeRecord(this.recordBuf);