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

@@ -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) {

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];

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) {

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.