Author: bodewig
Date: Mon Mar 23 09:10:50 2009
New Revision: 757357
URL: http://svn.apache.org/viewvc?rev=757357&view=rev
Log:
Javadoc improvements submitted by Christian Grobmeier, SANDBOX-305
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveEntry.java
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveInputStream.java
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveOutputStream.java
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveEntry.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveEntry.java?rev=757357&r1=757356&r2=757357&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveEntry.java
(original)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveEntry.java
Mon Mar 23 09:10:50 2009
@@ -23,50 +23,111 @@
/**
* A cpio archive consists of a sequence of files. There are several types of
* headers defided in two categories of new and old format. The headers are
- * recognized by magic numbers: "070701" ascii for "new" portable format
- * "070702" ascii for "new" portable format with CRC format "070707" ascii for
- * old ascii "070707" short for old binary CPIO 2.5 knows also about tar, but
it
- * is not recognized here.
- *
- * OLD FORMAT: Each file has a 76(ascii)/26(binary) byte header, a variable
- * length, NUL terminated filename, and variable length file data. A header for
- * a filename "TRAILER!!!" indicates the end of the archive.
- *
- * All the fields in the header are ISO 646 (approximately ASCII) strings of
- * octal numbers, left padded, not NUL terminated.
- *
- * Field Name Length in Bytes Notes ASCII / BINARY c_magic 6 / 2 c_dev 6 / 2
- * Device that contains a directory entry for this file c_ino 6 / 2 I-node
- * number that identifies the input file to the file system c_mode 6 / 2 Mode
of
- * the input file c_uid 6 / 2 User ID of the owner of the input file c_gid 6 /
2
- * Group ID of the owner of the input file c_nlink 6 / 2 Number of links that
- * are connected to the input file c_rdev 6 / 2 ID of the remote device from
- * which the input file is taken only valid for chr and blk special files
- * c_mtime 11 / 4 Time when data was last modified. For remote files, this
field
- * contains the time at the server c_namesize 6 / 2 Length of the path name,
- * including the terminating null byte c_filesize 11 / 4 Length of the file in
- * bytes. This is the length of the data section that follows the header
- * structure. Must be 0 for FIFOs and directories
- *
- * Special files, directories, and the trailer are recorded with the h_filesize
- * field equal to 0.
- *
- * NEW FORMAT: Each file has a 110 byte header, a variable length, NUL
- * terminated filename, and variable length file data. A header for a filename
- * "TRAILER!!!" indicates the end of the archive. All the fields in the header
- * are ISO 646 (approximately ASCII) strings of hexadecimal numbers, left
- * padded, not NUL terminated.
- *
- * Field Name Length in Bytes Notes c_magic 6 c_ino 8 c_mode 8 c_uid 8 c_gid 8
- * c_nlink 8 c_mtime 8 c_filesize 8 must be 0 for FIFOs and directories c_maj 8
- * c_min 8 c_rmaj 8 only valid for chr and blk special files c_rmin 8 only
valid
- * for chr and blk special files c_namesize 8 count includes terminating NUL in
- * pathname c_chksum 8 0 for "new" portable format; for CRC format the sum of
- * all the bytes in the file
+ * recognized by magic numbers:
*
- * This class uses mutable fields and is not considered to be threadsafe.
+ * <ul>
+ * <li>"070701" ASCII for new portable format</li>
+ * <li>"070702" ASCII for new portable format with CRC format</li>
+ * <li>"070707" ASCII for old ascii (also known as Portable ASCII, odc or old
+ * character format</li>
+ * <li>"070707" ASCII for old binary</li>
+ * </ul>
*
- * based on code from the jRPM project (jrpm.sourceforge.net)
+ * <p>The old binary format is limited to 16 bits for user id, group
+ * id, device, and inode numbers. It is limited to 4 gigabyte file
+ * sizes.
+ *
+ * The old ASCII format is limited to 18 bits for the user id, group
+ * id, device, and inode numbers. It is limited to 8 gigabyte file
+ * sizes.
+ *
+ * The new ASCII format is limited to 4 gigabyte file sizes.
+ *
+ * CPIO 2.5 knows also about tar, but it is not recognized here.</p>
+ *
+ *
+ * <h3>OLD FORMAT</h3>
+ *
+ * <p>Each file has a 76 (ascii) / 26 (binary) byte header, a variable
+ * length, NUL terminated filename, and variable length file data. A
+ * header for a filename "TRAILER!!!" indicates the end of the
+ * archive.</p>
+ *
+ * <p>All the fields in the header are ISO 646 (approximately ASCII)
+ * strings of octal numbers, left padded, not NUL terminated.</p>
+ *
+ * <pre>
+ * FIELDNAME NOTES
+ * c_magic The integer value octal 070707. This value can be used to
deter-
+ * mine whether this archive is written with little-endian or
big-
+ * endian integers.
+ * c_dev Device that contains a directory entry for this file
+ * c_ino I-node number that identifies the input file to the file
system
+ * c_mode The mode specifies both the regular permissions and the
file type.
+ * c_uid Numeric User ID of the owner of the input file
+ * c_gid Numeric Group ID of the owner of the input file
+ * c_nlink Number of links that are connected to the input file
+ * c_rdev For block special and character special entries, this
field
+ * contains the associated device number. For all other
entry types,
+ * it should be set to zero by writers and ignored by readers.
+ * c_mtime[2] Modification time of the file, indicated as the number of
seconds
+ * since the start of the epoch, 00:00:00 UTC January 1,
1970. The
+ * four-byte integer is stored with the most-significant 16
bits
+ * first followed by the least-significant 16 bits. Each of
the two
+ * 16 bit values are stored in machine-native byte order.
+ * c_namesize Length of the path name, including the terminating null
byte
+ * c_filesize[2] Length of the file in bytes. This is the length of the
data
+ * section that follows the header structure. Must be 0 for
+ * FIFOs and directories
+ *
+ * All fields are unsigned short fields with 16-bit integer values
+ * </pre>
+ *
+ * <p>Special files, directories, and the trailer are recorded with
+ * the h_filesize field equal to 0.</p>
+ *
+ *
+ * <h3>NEW FORMAT</h3>
+ *
+ * <p>Each file has a 110 byte header, a variable length, NUL
+ * terminated filename, and variable length file data. A header for a
+ * filename "TRAILER!!!" indicates the end of the archive. All the
+ * fields in the header are ISO 646 (approximately ASCII) strings of
+ * hexadecimal numbers, left padded, not NUL terminated.</p>
+ *
+ * <pre>
+ * FIELDNAME NOTES
+ * c_magic[6] The string 070701 for new ASCII, the string 070702 for new
ASCII with CRC
+ * c_ino[8]
+ * c_mode[8]
+ * c_uid[8]
+ * c_gid[8]
+ * c_nlink[8]
+ * c_mtim[8]
+ * c_filesize[8] must be 0 for FIFOs and directories
+ * c_maj[8]
+ * c_min[8]
+ * c_rmaj[8] only valid for chr and blk special files
+ * c_rmin[8] only valid for chr and blk special files
+ * c_namesize[8] count includes terminating NUL in pathname
+ * c_check[8] 0 for "new" portable format; for CRC format
+ * the sum of all the bytes in the file
+ * </pre>
+ *
+ * <p>New ASCII Format The "new" ASCII format uses 8-byte hexadecimal
+ * fields for all numbers and separates device numbers into separate
+ * fields for major and minor numbers.</p>
+ *
+ * <p>The pathname is followed by NUL bytes so that the total size of
+ * the fixed header plus pathname is a multiple of four. Likewise, the
+ * file data is padded to a multiple of four bytes.</p>
+ *
+ * <p>This class uses mutable fields and is not considered to be
+ * threadsafe.</p>
+ *
+ * <p>Based on code from the jRPM project (http://jrpm.sourceforge.net).
+ *
+ * @see http://people.freebsd.org/~kientzle/libarchive/man/cpio.5.txt
*/
public class CpioArchiveEntry implements CpioConstants, ArchiveEntry {
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveInputStream.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveInputStream.java?rev=757357&r1=757356&r2=757357&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveInputStream.java
(original)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveInputStream.java
Mon Mar 23 09:10:50 2009
@@ -36,8 +36,8 @@
* specified by the entry.
* <p/>
* <code><pre>
- * CPIOArchiveInputStream cpioIn = new CPIOArchiveInputStream(new
BufferedInputStream(
- * new FileInputStream(new File("test.cpio"))));
+ * CPIOArchiveInputStream cpioIn = new CPIOArchiveInputStream(
+ * new FileInputStream(new File("test.cpio")));
* CPIOArchiveEntry cpioEntry;
* <p/>
* while ((cpioEntry = cpioIn.getNextEntry()) != null) {
@@ -56,7 +56,7 @@
*
* This class uses mutable fields and is not considered to be threadsafe.
*
- * based on code from the jRPM project (jrpm.sourceforge.net)
+ * Based on code from the jRPM project (jrpm.sourceforge.net)
*/
public class CpioArchiveInputStream extends ArchiveInputStream implements
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveOutputStream.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveOutputStream.java?rev=757357&r1=757356&r2=757357&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveOutputStream.java
(original)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/cpio/CpioArchiveOutputStream.java
Mon Mar 23 09:10:50 2009
@@ -27,27 +27,27 @@
import org.apache.commons.compress.archivers.ArchiveOutputStream;
/**
- * CPIOArchiveOutputStream is a stream for writting cpio streams. All formats
of
- * cpio are supported (old ascii, old binary, new portable format and the new
- * portable format with crc).
+ * CPIOArchiveOutputStream is a stream for writing CPIO streams. All formats of
+ * CPIO are supported (old ASCII, old binary, new portable format and the new
+ * portable format with CRC).
* <p/>
* <p/>
- * An entry can be written by creating an instance of CPIOArchiveEntry and fill
- * it with the necessary values and put it into the cpio stream. Afterwards
- * write the contents of the file into the cpio stream. Either close the stream
+ * An entry can be written by creating an instance of CpioArchiveEntry and fill
+ * it with the necessary values and put it into the CPIO stream. Afterwards
+ * write the contents of the file into the CPIO stream. Either close the stream
* by calling finish() or put a next entry into the cpio stream.
* <p/>
* <code><pre>
- * CPIOArchiveOutputStream cpioOut = new CPIOArchiveOutputStream(new
BufferedOutputStream(
- * new FileOutputStream(new File("test.cpio"))));
- * CPIOArchiveEntry cpioEntry = new CPIOArchiveEntry();
- * cpioEntry.setName("testfile");
- * String testContents = "12345";
- * cpioEntry.setFileSize(testContents.length());
- * cpioOut.putNextEntry(cpioEntry);
- * cpioOut.write(testContents.getBytes());
- * cpioOut.finish();
- * cpioOut.close();
+ * CpioArchiveOutputStream out = new CpioArchiveOutputStream(
+ * new FileOutputStream(new File("test.cpio")));
+ * CpioArchiveEntry entry = new CpioArchiveEntry();
+ * entry.setName("testfile");
+ * String contents = "12345";
+ * entry.setFileSize(contents.length());
+ * out.putNextEntry(entry);
+ * out.write(testContents.getBytes());
+ * out.finish();
+ * out.close();
* </pre></code>
* <p/>
* Note: This implementation should be compatible to cpio 2.5
