From 302c66e3020540c9e47e301254dd8949738e071b Mon Sep 17 00:00:00 2001 From: Peter Reilly Date: Tue, 11 Jan 2005 18:41:21 +0000 Subject: [PATCH] javadoc git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@277343 13f79535-47bb-0310-9956-ffa450edef68 --- src/main/org/apache/tools/tar/TarBuffer.java | 43 ++++++++++++++++++- .../org/apache/tools/tar/TarInputStream.java | 26 ++++++++++- .../org/apache/tools/tar/TarOutputStream.java | 29 +++++++++++++ src/main/org/apache/tools/tar/TarUtils.java | 6 ++- 4 files changed, 101 insertions(+), 3 deletions(-) diff --git a/src/main/org/apache/tools/tar/TarBuffer.java b/src/main/org/apache/tools/tar/TarBuffer.java index 422d184ca..85ea3b6bb 100644 --- a/src/main/org/apache/tools/tar/TarBuffer.java +++ b/src/main/org/apache/tools/tar/TarBuffer.java @@ -42,7 +42,10 @@ import java.util.Arrays; public class TarBuffer { + /** Default record size */ public static final int DEFAULT_RCDSIZE = (512); + + /** Default block size */ public static final int DEFAULT_BLKSIZE = (DEFAULT_RCDSIZE * 20); private InputStream inStream; @@ -55,14 +58,29 @@ public class TarBuffer { private int recsPerBlock; private boolean debug; + /** + * Constructor for a TarBuffer on an input stream. + * @param inStream the input stream to use + */ public TarBuffer(InputStream inStream) { this(inStream, TarBuffer.DEFAULT_BLKSIZE); } + /** + * Constructor for a TarBuffer on an input stream. + * @param inStream the input stream to use + * @param blockSize the block size to use + */ public TarBuffer(InputStream inStream, int blockSize) { this(inStream, blockSize, TarBuffer.DEFAULT_RCDSIZE); } + /** + * Constructor for a TarBuffer on an input stream. + * @param inStream the input stream to use + * @param blockSize the block size to use + * @param recordSize the record size to use + */ public TarBuffer(InputStream inStream, int blockSize, int recordSize) { this.inStream = inStream; this.outStream = null; @@ -70,14 +88,29 @@ public class TarBuffer { this.initialize(blockSize, recordSize); } + /** + * Constructor for a TarBuffer on an output stream. + * @param outStream the output stream to use + */ public TarBuffer(OutputStream outStream) { this(outStream, TarBuffer.DEFAULT_BLKSIZE); } + /** + * Constructor for a TarBuffer on an output stream. + * @param outStream the output stream to use + * @param blockSize the block size to use + */ public TarBuffer(OutputStream outStream, int blockSize) { this(outStream, blockSize, TarBuffer.DEFAULT_RCDSIZE); } + /** + * Constructor for a TarBuffer on an output stream. + * @param outStream the output stream to use + * @param blockSize the block size to use + * @param recordSize the record size to use + */ public TarBuffer(OutputStream outStream, int blockSize, int recordSize) { this.inStream = null; this.outStream = outStream; @@ -106,6 +139,7 @@ public class TarBuffer { /** * Get the TAR Buffer's block size. Blocks consist of multiple records. + * @return the block size */ public int getBlockSize() { return this.blockSize; @@ -113,6 +147,7 @@ public class TarBuffer { /** * Get the TAR Buffer's record size. + * @return the record size */ public int getRecordSize() { return this.recordSize; @@ -132,6 +167,7 @@ public class TarBuffer { * archive is indicated by a record that consists entirely of null bytes. * * @param record The record data to check. + * @return true if the record data is an End of Archive */ public boolean isEOFRecord(byte[] record) { for (int i = 0, sz = this.getRecordSize(); i < sz; ++i) { @@ -145,6 +181,7 @@ public class TarBuffer { /** * Skip over a record on the input stream. + * @throws IOException on error */ public void skipRecord() throws IOException { if (this.debug) { @@ -169,6 +206,7 @@ public class TarBuffer { * Read a record from the input stream and return the data. * * @return The record data. + * @throws IOException on error */ public byte[] readRecord() throws IOException { if (this.debug) { @@ -232,7 +270,7 @@ public class TarBuffer { // Thanks to 'Yohann.Roussel@alcatel.fr' for this fix. // if (numBytes == -1) { - // However, just leaving the unread portion of the buffer dirty does + // However, just leaving the unread portion of the buffer dirty does // cause problems in some cases. This problem is described in // http://issues.apache.org/bugzilla/show_bug.cgi?id=29877 // @@ -283,6 +321,7 @@ public class TarBuffer { * Write an archive record to the archive. * * @param record The record data to write to the archive. + * @throws IOException on error */ public void writeRecord(byte[] record) throws IOException { if (this.debug) { @@ -319,6 +358,7 @@ public class TarBuffer { * * @param buf The buffer containing the record data to write. * @param offset The offset of the record data within buf. + * @throws IOException on error */ public void writeRecord(byte[] buf, int offset) throws IOException { if (this.debug) { @@ -387,6 +427,7 @@ public class TarBuffer { /** * Close the TarBuffer. If this is an output buffer, also flush the * current block before closing. + * @throws IOException on error */ public void close() throws IOException { if (this.debug) { diff --git a/src/main/org/apache/tools/tar/TarInputStream.java b/src/main/org/apache/tools/tar/TarInputStream.java index fdcdac173..50cc863df 100644 --- a/src/main/org/apache/tools/tar/TarInputStream.java +++ b/src/main/org/apache/tools/tar/TarInputStream.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2004 The Apache Software Foundation + * Copyright 2000-2005 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -46,14 +46,29 @@ public class TarInputStream extends FilterInputStream { protected TarEntry currEntry; private boolean v7Format; + /** + * Constructor for TarInputStream. + * @param is the input stream to use + */ public TarInputStream(InputStream is) { this(is, TarBuffer.DEFAULT_BLKSIZE, TarBuffer.DEFAULT_RCDSIZE); } + /** + * Constructor for TarInputStream. + * @param is the input stream to use + * @param blockSize the block size to use + */ public TarInputStream(InputStream is, int blockSize) { this(is, blockSize, TarBuffer.DEFAULT_RCDSIZE); } + /** + * Constructor for TarInputStream. + * @param is the input stream to use + * @param blockSize the block size to use + * @param recordSize the record size to use + */ public TarInputStream(InputStream is, int blockSize, int recordSize) { super(is); @@ -77,6 +92,7 @@ public class TarInputStream extends FilterInputStream { /** * Closes this stream. Calls the TarBuffer's close() method. + * @throws IOException on error */ public void close() throws IOException { this.buffer.close(); @@ -100,6 +116,7 @@ public class TarInputStream extends FilterInputStream { * * * @return The number of available bytes for the current entry. + * @throws IOException for signature */ public int available() throws IOException { return this.entrySize - this.entryOffset; @@ -112,6 +129,8 @@ public class TarInputStream extends FilterInputStream { * to skip extends beyond that point. * * @param numToSkip The number of bytes to skip. + * @return the number actually skipped + * @throws IOException on error */ public long skip(long numToSkip) throws IOException { // REVIEW @@ -165,6 +184,7 @@ public class TarInputStream extends FilterInputStream { * been reached. * * @return The next TarEntry in the archive, or null. + * @throws IOException on error */ public TarEntry getNextEntry() throws IOException { if (this.hasHitEOF) { @@ -254,6 +274,7 @@ public class TarInputStream extends FilterInputStream { * This method simply calls read( byte[], int, int ). * * @return The byte read, or -1 at EOF. + * @throws IOException on error */ public int read() throws IOException { int num = this.read(this.oneBuf, 0, 1); @@ -272,6 +293,7 @@ public class TarInputStream extends FilterInputStream { * * @param buf The buffer into which to place bytes read. * @return The number of bytes read, or -1 at EOF. + * @throws IOException on error */ public int read(byte[] buf) throws IOException { return this.read(buf, 0, buf.length); @@ -288,6 +310,7 @@ public class TarInputStream extends FilterInputStream { * @param offset The offset at which to place bytes read. * @param numToRead The number of bytes to read. * @return The number of bytes read, or -1 at EOF. + * @throws IOException on error */ public int read(byte[] buf, int offset, int numToRead) throws IOException { int totalRead = 0; @@ -361,6 +384,7 @@ public class TarInputStream extends FilterInputStream { * an output stream. * * @param out The OutputStream into which to write the entry's data. + * @throws IOException on error */ public void copyEntryContents(OutputStream out) throws IOException { byte[] buf = new byte[32 * 1024]; diff --git a/src/main/org/apache/tools/tar/TarOutputStream.java b/src/main/org/apache/tools/tar/TarOutputStream.java index 7b2395b21..03c3dc968 100644 --- a/src/main/org/apache/tools/tar/TarOutputStream.java +++ b/src/main/org/apache/tools/tar/TarOutputStream.java @@ -52,14 +52,29 @@ public class TarOutputStream extends FilterOutputStream { protected TarBuffer buffer; protected int longFileMode = LONGFILE_ERROR; + /** + * Constructor for TarInputStream. + * @param os the output stream to use + */ public TarOutputStream(OutputStream os) { this(os, TarBuffer.DEFAULT_BLKSIZE, TarBuffer.DEFAULT_RCDSIZE); } + /** + * Constructor for TarInputStream. + * @param os the output stream to use + * @param blockSize the block size to use + */ public TarOutputStream(OutputStream os, int blockSize) { this(os, blockSize, TarBuffer.DEFAULT_RCDSIZE); } + /** + * Constructor for TarInputStream. + * @param os the output stream to use + * @param blockSize the block size to use + * @param recordSize the record size to use + */ public TarOutputStream(OutputStream os, int blockSize, int recordSize) { super(os); @@ -71,6 +86,13 @@ public class TarOutputStream extends FilterOutputStream { this.oneBuf = new byte[1]; } + /** + * 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 + */ public void setLongFileMode(int longFileMode) { this.longFileMode = longFileMode; } @@ -97,6 +119,7 @@ public class TarOutputStream extends FilterOutputStream { /** * 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 */ public void finish() throws IOException { // See Bugzilla 28776 for a discussion on this @@ -109,6 +132,7 @@ public class TarOutputStream extends FilterOutputStream { * 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 */ public void close() throws IOException { this.finish(); @@ -134,6 +158,7 @@ public class TarOutputStream extends FilterOutputStream { * is completely written to the output stream. * * @param entry The TarEntry to be written to the archive. + * @throws IOException on error */ public void putNextEntry(TarEntry entry) throws IOException { if (entry.getName().length() >= TarConstants.NAMELEN) { @@ -176,6 +201,7 @@ public class TarOutputStream extends FilterOutputStream { * 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 */ public void closeEntry() throws IOException { if (this.assemLen > 0) { @@ -202,6 +228,7 @@ public class TarOutputStream extends FilterOutputStream { * This method simply calls read( byte[], int, int ). * * @param b The byte written. + * @throws IOException on error */ public void write(int b) throws IOException { this.oneBuf[0] = (byte) b; @@ -215,6 +242,7 @@ public class TarOutputStream extends FilterOutputStream { * This method simply calls write( byte[], int, int ). * * @param wBuf The buffer to write to the archive. + * @throws IOException on error */ public void write(byte[] wBuf) throws IOException { this.write(wBuf, 0, wBuf.length); @@ -232,6 +260,7 @@ public class TarOutputStream extends FilterOutputStream { * @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 */ public void write(byte[] wBuf, int wOffset, int numToWrite) throws IOException { if ((this.currBytes + numToWrite) > this.currSize) { diff --git a/src/main/org/apache/tools/tar/TarUtils.java b/src/main/org/apache/tools/tar/TarUtils.java index 5af7c5fa3..0e97aceb1 100644 --- a/src/main/org/apache/tools/tar/TarUtils.java +++ b/src/main/org/apache/tools/tar/TarUtils.java @@ -1,5 +1,5 @@ /* - * Copyright 2000,2002,2004 The Apache Software Foundation + * Copyright 2000,2002,2004-2005 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -91,6 +91,7 @@ public class TarUtils { * Determine the number of bytes in an entry name. * * @param name The header name from which to parse. + * @param buf The buffer from which to parse. * @param offset The offset into the buffer from which to parse. * @param length The number of header bytes to parse. * @return The number of bytes in a header's entry name. @@ -113,6 +114,7 @@ public class TarUtils { * Parse an octal integer from a header buffer. * * @param value The header value + * @param buf The buffer from which to parse. * @param offset The offset into the buffer from which to parse. * @param length The number of header bytes to parse. * @return The integer value of the octal bytes. @@ -146,6 +148,7 @@ public class TarUtils { * Parse an octal long integer from a header buffer. * * @param value The header value + * @param buf The buffer from which to parse. * @param offset The offset into the buffer from which to parse. * @param length The number of header bytes to parse. * @return The long value of the octal bytes. @@ -163,6 +166,7 @@ public class TarUtils { * Parse the checksum octal integer from a header buffer. * * @param value The header value + * @param buf The buffer from which to parse. * @param offset The offset into the buffer from which to parse. * @param length The number of header bytes to parse. * @return The integer value of the entry's checksum.