You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by bo...@apache.org on 2013/10/10 22:12:15 UTC
svn commit: r1531095 - in
/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress:
archivers/arj/ archivers/sevenz/ utils/
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);