commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject svn commit: r1531095 - in /commons/proper/compress/trunk/src/main/java/org/apache/commons/compress: archivers/arj/ archivers/sevenz/ utils/
Date Thu, 10 Oct 2013 20:12:15 GMT
Author: bodewig
Date: Thu Oct 10 20:12:15 2013
New Revision: 1531095

URL: http://svn.apache.org/r1531095
Log:
javadocs

Modified:
    commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveEntry.java
    commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveInputStream.java
    commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZArchiveEntry.java
    commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZFile.java
    commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZOutputFile.java
    commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/BoundedInputStream.java
    commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/CRC32VerifyingInputStream.java

Modified: commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveEntry.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveEntry.java?rev=1531095&r1=1531094&r2=1531095&view=diff
==============================================================================
--- commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveEntry.java
(original)
+++ commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveEntry.java
Thu Oct 10 20:12:15 2013
@@ -28,6 +28,7 @@ import org.apache.commons.compress.archi
  * An entry in an ARJ archive.
  * 
  * @NotThreadSafe
+ * @since 1.6
  */
 public class ArjArchiveEntry implements ArchiveEntry {
     private final LocalFileHeader localFileHeader;
@@ -40,6 +41,11 @@ public class ArjArchiveEntry implements 
         this.localFileHeader = localFileHeader;
     }
 
+    /**
+     * Get this entry's name.
+     *
+     * @return This entry's name.
+     */
     public String getName() {
         if ((localFileHeader.arjFlags & LocalFileHeader.Flags.PATHSYM) != 0) {
             return localFileHeader.name.replaceAll("/",
@@ -49,14 +55,23 @@ public class ArjArchiveEntry implements 
         }
     }
 
+    /**
+     * Get this entry's file size.
+     *
+     * @return This entry's file size.
+     */
     public long getSize() {
         return localFileHeader.originalSize;
     }
 
+    /** True if the entry refers to a directory */
     public boolean isDirectory() {
         return localFileHeader.fileType == LocalFileHeader.FileTypes.DIRECTORY;
     }
 
+    /**
+     * The last modified date of the entry.
+     */
     public Date getLastModifiedDate() {
         long ts = isHostOsUnix() ? (localFileHeader.dateTimeModified * 1000l)
             : ZipUtil.dosToJavaTime(0xFFFFFFFFL & localFileHeader.dateTimeModified);

Modified: commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveInputStream.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveInputStream.java?rev=1531095&r1=1531094&r2=1531095&view=diff
==============================================================================
--- commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveInputStream.java
(original)
+++ commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/arj/ArjArchiveInputStream.java
Thu Oct 10 20:12:15 2013
@@ -37,6 +37,7 @@ import org.apache.commons.compress.utils
  * <p>
  * <a href="http://farmanager.com/svn/trunk/plugins/multiarc/arc.doc/arj.txt">Reference</a>
  * @NotThreadSafe
+ * @since 1.6
  */
 public class ArjArchiveInputStream extends ArchiveInputStream {
     private static final boolean DEBUG = false;
@@ -289,16 +290,31 @@ public class ArjArchiveInputStream exten
         return localFileHeader;
     }
     
+    /**
+     * Checks if the signature matches what is expected for an arj file.
+     *
+     * @param signature
+     *            the bytes to check
+     * @param length
+     *            the number of bytes to check
+     * @return true, if this stream is an arj archive stream, false otherwise
+     */
     public static boolean matches(final byte[] signature, final int length) {
         return length >= 2 &&
                 (0xff & signature[0]) == ARJ_MAGIC_1 &&
                 (0xff & signature[1]) == ARJ_MAGIC_2;
     }
     
+    /**
+     * Gets the archive's recorded name.
+     */
     public String getArchiveName() {
         return mainHeader.name;
     }
     
+    /**
+     * Gets the archive's comment.
+     */
     public String getArchiveComment() {
         return mainHeader.comment;
     }

Modified: commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZArchiveEntry.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZArchiveEntry.java?rev=1531095&r1=1531094&r2=1531095&view=diff
==============================================================================
--- commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZArchiveEntry.java
(original)
+++ commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZArchiveEntry.java
Thu Oct 10 20:12:15 2013
@@ -27,6 +27,7 @@ import org.apache.commons.compress.archi
  * An entry in a 7z archive.
  * 
  * @NotThreadSafe
+ * @since 1.6
  */
 public class SevenZArchiveEntry implements ArchiveEntry {
     private String name;
@@ -47,27 +48,55 @@ public class SevenZArchiveEntry implemen
     
     public SevenZArchiveEntry() {
     }
-    
+
+    /**
+     * Get this entry's name.
+     *
+     * @return This entry's name.
+     */
     public String getName() {
         return name;
     }
     
+    /**
+     * Set this entry's name.
+     *
+     * @param name This entry's new name.
+     */
     public void setName(String name) {
         this.name = name;
     }
 
+    /**
+     * Whether there is any content associated with this entry.
+     * @return whether there is any content associated with this entry.
+     */
     public boolean hasStream() {
         return hasStream;
     }
 
+    /**
+     * Sets whether there is any content associated with this entry.
+     * @param hasStream whether there is any content associated with this entry.
+     */
     public void setHasStream(boolean hasStream) {
         this.hasStream = hasStream;
     }
 
+    /**
+     * Return whether or not this entry represents a directory.
+     *
+     * @return True if this entry is a directory.
+     */
     public boolean isDirectory() {
         return isDirectory;
     }
     
+    /**
+     * Sets whether or not this entry represents a directory.
+     *
+     * @param isDirectory True if this entry is a directory.
+     */
     public void setDirectory(boolean isDirectory) {
         this.isDirectory = isDirectory;
     }
@@ -90,14 +119,25 @@ public class SevenZArchiveEntry implemen
         this.isAntiItem = isAntiItem;
     }
 
+    /**
+     * Returns whether this entry has got a creation date at all.
+     */
     public boolean getHasCreationDate() {
         return hasCreationDate;
     }
     
+    /**
+     * Sets whether this entry has got a creation date at all.
+     */
     public void setHasCreationDate(boolean hasCreationDate) {
         this.hasCreationDate = hasCreationDate;
     }
     
+    /**
+     * Gets the creation date.
+     * @throws UnsupportedOperationException if the entry hasn't got a
+     * creation date.
+     */
     public Date getCreationDate() {
         if (hasCreationDate) {
             return ntfsTimeToJavaTime(creationDate);
@@ -107,10 +147,17 @@ public class SevenZArchiveEntry implemen
         }
     }
     
+    /**
+     * Sets the creation date using NTFS time (100 nanosecond units
+     * since 1 January 1601)
+     */
     public void setCreationDate(long ntfsCreationDate) {
         this.creationDate = ntfsCreationDate;
     }
     
+    /**
+     * Sets the creation date,
+     */
     public void setCreationDate(Date creationDate) {
         hasCreationDate = creationDate != null;
         if (hasCreationDate) {
@@ -118,14 +165,25 @@ public class SevenZArchiveEntry implemen
         }
     }
 
+    /**
+     * Returns whether this entry has got a last modified date at all.
+     */
     public boolean getHasLastModifiedDate() {
         return hasLastModifiedDate;
     }
 
+    /**
+     * Sets whether this entry has got a last modified date at all.
+     */
     public void setHasLastModifiedDate(boolean hasLastModifiedDate) {
         this.hasLastModifiedDate = hasLastModifiedDate;
     }
 
+    /**
+     * Gets the last modified date.
+     * @throws UnsupportedOperationException if the entry hasn't got a
+     * last modified date.
+     */
     public Date getLastModifiedDate() {
         if (hasLastModifiedDate) {
             return ntfsTimeToJavaTime(lastModifiedDate);
@@ -135,10 +193,17 @@ public class SevenZArchiveEntry implemen
         }
     }
     
+    /**
+     * Sets the last modified date using NTFS time (100 nanosecond
+     * units since 1 January 1601)
+     */
     public void setLastModifiedDate(long ntfsLastModifiedDate) {
         this.lastModifiedDate = ntfsLastModifiedDate;
     }
     
+    /**
+     * Sets the last modified date,
+     */
     public void setLastModifiedDate(Date lastModifiedDate) {
         hasLastModifiedDate = lastModifiedDate != null;
         if (hasLastModifiedDate) {
@@ -146,14 +211,25 @@ public class SevenZArchiveEntry implemen
         }
     }
     
+    /**
+     * Returns whether this entry has got an access date at all.
+     */
     public boolean getHasAccessDate() {
         return hasAccessDate;
     }
 
+    /**
+     * Sets whether this entry has got an access date at all.
+     */
     public void setHasAccessDate(boolean hasAcessDate) {
         this.hasAccessDate = hasAcessDate;
     }
 
+    /**
+     * Gets the access date.
+     * @throws UnsupportedOperationException if the entry hasn't got a
+     * access date.
+     */
     public Date getAccessDate() {
         if (hasAccessDate) {
             return ntfsTimeToJavaTime(accessDate);
@@ -163,10 +239,17 @@ public class SevenZArchiveEntry implemen
         }
     }
     
+    /**
+     * Sets the access date using NTFS time (100 nanosecond units
+     * since 1 January 1601)
+     */
     public void setAccessDate(long ntfsAccessDate) {
         this.accessDate = ntfsAccessDate;
     }
     
+    /**
+     * Sets the access date,
+     */
     public void setAccessDate(Date accessDate) {
         hasAccessDate = accessDate != null;
         if (hasAccessDate) {
@@ -174,42 +257,78 @@ public class SevenZArchiveEntry implemen
         }
     }
 
+    /**
+     * Returns whether this entry has windows attributes.
+     */
     public boolean getHasWindowsAttributes() {
         return hasWindowsAttributes;
     }
 
+    /**
+     * Sets whether this entry has windows attributes.
+     */
     public void setHasWindowsAttributes(boolean hasWindowsAttributes) {
         this.hasWindowsAttributes = hasWindowsAttributes;
     }
 
+    /**
+     * Gets the windows attributes.
+     */
     public int getWindowsAttributes() {
         return windowsAttributes;
     }
 
+    /**
+     * Sets the windows attributes.
+     */
     public void setWindowsAttributes(int windowsAttributes) {
         this.windowsAttributes = windowsAttributes;
     }
 
+    /**
+     * Returns whether this entry has got a crc.
+     *
+     * In general entries without streams don't have a CRC either.
+     */
     public boolean getHasCrc() {
         return hasCrc;
     }
 
+    /**
+     * Sets whether this entry has got a crc.
+     */
     public void setHasCrc(boolean hasCrc) {
         this.hasCrc = hasCrc;
     }
 
+    /**
+     * Gets the CRC.
+     */
     public int getCrc() {
         return crc;
     }
 
+    /**
+     * Sets the CRC.
+     */
     public void setCrc(int crc) {
         this.crc = crc;
     }
 
+    /**
+     * Get this entry's file size.
+     *
+     * @return This entry's file size.
+     */
     public long getSize() {
         return size;
     }
     
+    /**
+     * Set this entry's file size.
+     *
+     * @param size This entry's new file size.
+     */
     public void setSize(long size) {
         this.size = size;
     }

Modified: commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZFile.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZFile.java?rev=1531095&r1=1531094&r2=1531095&view=diff
==============================================================================
--- commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZFile.java
(original)
+++ commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZFile.java
Thu Oct 10 20:12:15 2013
@@ -59,6 +59,7 @@ import org.apache.commons.compress.utils
  * encryption isn't plausibly deniable.
  * 
  * @NotThreadSafe
+ * @since 1.6
  */
 public class SevenZFile {
     private static final boolean DEBUG = false;
@@ -75,6 +76,12 @@ public class SevenZFile {
         (byte)'7', (byte)'z', (byte)0xBC, (byte)0xAF, (byte)0x27, (byte)0x1C
     };
     
+    /**
+     * Reads a file as 7z archive
+     *
+     * @param filename the file to read
+     * @param password optional password if the archive is encrypted
+     */
     public SevenZFile(final File filename, final String password) throws IOException {
         boolean succeeded = false;
         this.password = password;
@@ -89,10 +96,18 @@ public class SevenZFile {
         }
     }
     
+    /**
+     * Reads a file as unecrypted 7z archive
+     *
+     * @param filename the file to read
+     */
     public SevenZFile(final File filename) throws IOException {
         this(filename, null);
     }
 
+    /**
+     * Closes the archive.
+     */
     public void close() {
         if (file != null) {
             try {
@@ -115,6 +130,13 @@ public class SevenZFile {
         }
     }
     
+    /**
+     * Returns the next Archive Entry in this archive.
+     *
+     * @return the next entry,
+     *         or {@code null} if there are no more entries
+     * @throws IOException if the next entry could not be read
+     */
     public SevenZArchiveEntry getNextEntry() throws IOException {
         if (currentEntryIndex >= (archive.files.length - 1)) {
             return null;

Modified: commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZOutputFile.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZOutputFile.java?rev=1531095&r1=1531094&r2=1531095&view=diff
==============================================================================
--- commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZOutputFile.java
(original)
+++ commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/sevenz/SevenZOutputFile.java
Thu Oct 10 20:12:15 2013
@@ -33,6 +33,7 @@ import org.apache.commons.compress.archi
 
 /**
  * Writes a 7z file.
+ * @since 1.6
  */
 public class SevenZOutputFile {
     private final RandomAccessFile file;
@@ -47,6 +48,9 @@ public class SevenZOutputFile {
         file.seek(SevenZFile.SIGNATURE_HEADER_SIZE);
     }
     
+    /**
+     * Closes the archive, calling {@link #finish} if necessary.
+     */
     public void close() {
         try {
             if (!finished) {
@@ -57,6 +61,15 @@ public class SevenZOutputFile {
         }
     }
     
+    /**
+     * Create an archive entry using the inputFile and entryName provided.
+     * 
+     * @param inputFile
+     * @param entryName 
+     * @return the ArchiveEntry set up with details from the file
+     * 
+     * @throws IOException
+     */
     public SevenZArchiveEntry createArchiveEntry(final File inputFile,
             final String entryName) throws IOException {
         final SevenZArchiveEntry entry = new SevenZArchiveEntry();
@@ -66,11 +79,24 @@ public class SevenZOutputFile {
         return entry;
     }
 
+    /**
+     * Records an archive entry to add.
+     *
+     * The caller must then write the content to the archive and call
+     * {@link #closeArchiveEntry()} to complete the process.
+     * 
+     * @param entry describes the entry
+     * @throws IOException
+     */
     public void putArchiveEntry(final ArchiveEntry archiveEntry) throws IOException {
         final SevenZArchiveEntry entry = (SevenZArchiveEntry) archiveEntry;
         files.add(entry);
     }
     
+    /**
+     * Closes the archive entry.
+     * @throws IOException
+     */
     public void closeArchiveEntry() throws IOException {
         final SevenZArchiveEntry entry = files.get(files.size() - 1);
         if (fileBytesWritten > 0) {
@@ -88,22 +114,44 @@ public class SevenZOutputFile {
         fileBytesWritten = 0;
     }
     
+    /**
+     * Writes a byte to the current archive entry.
+     * @param b The byte to be written.
+     * @throws IOException on error
+     */
     public void write(final int b) throws IOException {
         file.write(b);
         crc32.update(b);
         fileBytesWritten++;
     }
     
+    /**
+     * Writes a byte array to the current archive entry.
+     * @param b The byte array to be written.
+     * @throws IOException on error
+     */
     public void write(final byte[] b) throws IOException {
         write(b, 0, b.length);
     }
     
+    /**
+     * Writes part of a byte array to the current archive entry.
+     * @param b The byte array to be written.
+     * @param off offset into the array to start writing from
+     * @param len number of bytes to write
+     * @throws IOException on error
+     */
     public void write(final byte[] b, final int off, final int len) throws IOException {
         file.write(b, off, len);
         crc32.update(b, off, len);
         fileBytesWritten += len;
     }
     
+    /**
+     * Finishes the addition of entries to this archive, without closing it.
+     * 
+     * @throws IOException if archive is already closed.
+     */
     public void finish() throws IOException {
         if (finished) {
             throw new IOException("This archive has already been finished");

Modified: commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/BoundedInputStream.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/BoundedInputStream.java?rev=1531095&r1=1531094&r2=1531095&view=diff
==============================================================================
--- commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/BoundedInputStream.java
(original)
+++ commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/BoundedInputStream.java
Thu Oct 10 20:12:15 2013
@@ -20,6 +20,11 @@ package org.apache.commons.compress.util
 import java.io.IOException;
 import java.io.InputStream;
 
+/**
+ * A stream that limits reading from a wrapped stream to a given number of bytes.
+ * @NotThreadSafe
+ * @since 1.6
+ */
 public class BoundedInputStream extends InputStream {
     private final InputStream in;
     private long bytesRemaining;
@@ -58,4 +63,4 @@ public class BoundedInputStream extends 
     @Override
     public void close() {
     }
-}
\ No newline at end of file
+}

Modified: commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/CRC32VerifyingInputStream.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/CRC32VerifyingInputStream.java?rev=1531095&r1=1531094&r2=1531095&view=diff
==============================================================================
--- commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/CRC32VerifyingInputStream.java
(original)
+++ commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/utils/CRC32VerifyingInputStream.java
Thu Oct 10 20:12:15 2013
@@ -21,6 +21,12 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.util.zip.CRC32;
 
+/**
+ * A stream that verifies the CRC of the data read once the stream is
+ * exhausted.
+ * @NotThreadSafe
+ * @since 1.6
+ */
 public class CRC32VerifyingInputStream extends InputStream {
     private final InputStream in;
     private long bytesRemaining;
@@ -33,6 +39,12 @@ public class CRC32VerifyingInputStream e
         this.bytesRemaining = size;
     }
 
+    /**
+     * Reads a single byte from the stream
+     * @throws IOException if the underlying stream throws or the
+     * stream is exhausted and the CRC doesn't match the expected
+     * value
+     */
     @Override
     public int read() throws IOException {
         if (bytesRemaining <= 0) {
@@ -49,11 +61,23 @@ public class CRC32VerifyingInputStream e
         return ret;
     }
 
+    /**
+     * Reads a byte array from the stream
+     * @throws IOException if the underlying stream throws or the
+     * stream is exhausted and the CRC doesn't match the expected
+     * value
+     */
     @Override
     public int read(byte[] b) throws IOException {
         return read(b, 0, b.length);
     }
 
+    /**
+     * Reads from the stream into a byte array.
+     * @throws IOException if the underlying stream throws or the
+     * stream is exhausted and the CRC doesn't match the expected
+     * value
+     */
     @Override
     public int read(byte[] b, int off, int len) throws IOException {
         int ret = in.read(b, off, len);



Mime
View raw message