You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2025/08/10 20:33:50 UTC
(commons-compress) 03/04: Javadoc
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-compress.git
commit d80627a7cc954f028cf859ba0f30e84f77686acd
Author: Gary D. Gregory <ga...@gmail.com>
AuthorDate: Sun Aug 10 16:14:23 2025 -0400
Javadoc
Reduce vertical whitespace
---
.../compress/archivers/tar/TarArchiveEntry.java | 47 ++++------
.../archivers/tar/TarArchiveInputStream.java | 100 +++++++++-----------
.../archivers/tar/TarArchiveOutputStream.java | 50 ++++------
.../archivers/tar/TarArchiveSparseEntry.java | 2 +-
.../tar/TarArchiveSparseZeroInputStream.java | 6 +-
.../commons/compress/archivers/tar/TarFile.java | 104 ++++++++-------------
.../commons/compress/archivers/tar/TarUtils.java | 16 ++--
7 files changed, 135 insertions(+), 190 deletions(-)
diff --git a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveEntry.java b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveEntry.java
index 75e5ce3cb..2679823f9 100644
--- a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveEntry.java
+++ b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveEntry.java
@@ -232,15 +232,12 @@ private static String normalizeFileName(String fileName, final boolean preserveA
final String property = SystemProperties.getOsName();
if (property != null) {
final String osName = StringUtils.toRootLowerCase(property);
-
// Strip off drive letters!
// REVIEW Would a better check be "(File.separator == '\')"?
-
if (osName.startsWith("windows")) {
if (fileName.length() > 2) {
final char ch1 = fileName.charAt(0);
final char ch2 = fileName.charAt(1);
-
if (ch2 == ':' && (ch1 >= 'a' && ch1 <= 'z' || ch1 >= 'A' && ch1 <= 'Z')) {
fileName = fileName.substring(2);
}
@@ -253,9 +250,7 @@ private static String normalizeFileName(String fileName, final boolean preserveA
}
}
}
-
fileName = fileName.replace(File.separatorChar, '/');
-
// No absolute pathnames
// Windows (and Posix?) paths can start with "\\NetworkDrive\",
// so we loop on starting /'s.
@@ -270,7 +265,6 @@ private static Instant parseInstantFromDecimalSeconds(final String value) throws
if (!PAX_EXTENDED_HEADER_FILE_TIMES_PATTERN.matcher(value).matches()) {
throw new ArchiveException("Corrupted PAX header. Time field value is invalid '%s'", value);
}
-
final BigDecimal epochSeconds = new BigDecimal(value);
final long seconds = epochSeconds.longValue();
final long nanos = epochSeconds.remainder(BigDecimal.ONE).movePointRight(9).longValue();
@@ -354,7 +348,7 @@ private static Instant parseInstantFromDecimalSeconds(final String value) throws
/** The entry's minor device number. */
private int devMinor;
- /** The sparse headers in tar */
+ /** The sparse headers in tar. */
private List<TarArchiveStructSparse> sparseHeaders;
/** If an extension sparse header follows. */
@@ -367,20 +361,20 @@ private static Instant parseInstantFromDecimalSeconds(final String value) throws
private boolean paxGNUSparse;
/**
- * is this entry a GNU sparse entry using 1.X PAX formats? the sparse headers of 1.x PAX Format is stored in file data block
+ * is this entry a GNU sparse entry using 1.X PAX formats? the sparse headers of 1.x PAX Format is stored in file data block.
*/
private boolean paxGNU1XSparse;
/** Is this entry a star sparse entry using the PAX header? */
private boolean starSparse;
- /** The entry's file reference */
+ /** The entry's file reference. */
private final Path file;
- /** The entry's file linkOptions */
+ /** The entry's file linkOptions. */
private final LinkOption[] linkOptions;
- /** Extra, user supplied pax headers */
+ /** Extra, user supplied pax headers. */
private final Map<String, String> extraPaxHeaders = new HashMap<>();
private long dataOffset = OFFSET_UNKNOWN;
@@ -403,7 +397,7 @@ private TarArchiveEntry(final boolean preserveAbsolutePath) {
* Constructs an entry from an archive's header bytes. File is set to null.
*
* @param headerBuf The header bytes from a tar archive entry.
- * @throws IllegalArgumentException if any of the numeric fields have an invalid format
+ * @throws IllegalArgumentException if any of the numeric fields have an invalid format.
*/
public TarArchiveEntry(final byte[] headerBuf) {
this(false);
@@ -414,8 +408,8 @@ public TarArchiveEntry(final byte[] headerBuf) {
* Constructs an entry from an archive's header bytes. File is set to null.
*
* @param headerBuf The header bytes from a tar archive entry.
- * @param encoding encoding to use for file names
- * @throws IllegalArgumentException if any of the numeric fields have an invalid format
+ * @param encoding encoding to use for file names.
+ * @throws IllegalArgumentException if any of the numeric fields have an invalid format.
* @throws IOException on error
* @since 1.4
*/
@@ -427,11 +421,11 @@ public TarArchiveEntry(final byte[] headerBuf, final ZipEncoding encoding) throw
* Constructs an entry from an archive's header bytes. File is set to null.
*
* @param headerBuf The header bytes from a tar archive entry.
- * @param encoding encoding to use for file names
+ * @param encoding encoding to use for file names.
* @param lenient when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to
* {@link #UNKNOWN}. When set to false such illegal fields cause an exception instead.
- * @throws IllegalArgumentException if any of the numeric fields have an invalid format
- * @throws IOException on error
+ * @throws IllegalArgumentException if any of the numeric fields have an invalid format.
+ * @throws IOException on error.
* @since 1.19
*/
public TarArchiveEntry(final byte[] headerBuf, final ZipEncoding encoding, final boolean lenient) throws IOException {
@@ -516,11 +510,11 @@ public TarArchiveEntry(final File file, final String fileName) {
*
* @param globalPaxHeaders the parsed global PAX headers, or null if this is the first one.
* @param headerBuf The header bytes from a tar archive entry.
- * @param encoding encoding to use for file names
+ * @param encoding encoding to use for file names.
* @param lenient when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to
* {@link #UNKNOWN}. When set to false such illegal fields cause an exception instead.
- * @throws IllegalArgumentException if any of the numeric fields have an invalid format
- * @throws IOException on error
+ * @throws IllegalArgumentException if any of the numeric fields have an invalid format.
+ * @throws IOException on error.
* @since 1.22
*/
public TarArchiveEntry(final Map<String, String> globalPaxHeaders, final byte[] headerBuf, final ZipEncoding encoding, final boolean lenient)
@@ -574,7 +568,7 @@ public TarArchiveEntry(final Path file) throws IOException {
* @param file The file that the entry represents.
* @param fileName the name to be used for the entry.
* @param linkOptions options indicating how symbolic links are handled.
- * @throws IOException if an I/O error occurs
+ * @throws IOException if an I/O error occurs.
* @since 1.21
*/
public TarArchiveEntry(final Path file, final String fileName, final LinkOption... linkOptions) throws IOException {
@@ -643,7 +637,7 @@ public TarArchiveEntry(final String name, final byte linkFlag) {
* letters are stripped if {@code preserveAbsolutePath} is {@code false}.
* </p>
*
- * @param name the entry name
+ * @param name the entry name.
* @param linkFlag the entry link flag.
* @param preserveAbsolutePath whether to allow leading slashes or drive letters in the name.
* @since 1.5
@@ -1604,8 +1598,8 @@ private void parseUstarHeaderBlock(final Map<String, String> globalPaxHeaders, f
/**
* Processes one pax header, using the entries extraPaxHeaders map as source for extra headers used when handling entries for sparse files.
*
- * @param key
- * @param val
+ * @param key the header name.
+ * @param val the header value.
* @since 1.15
*/
private void processPaxHeader(final String key, final String val) throws IOException {
@@ -1704,7 +1698,6 @@ private void readFileMode(final Path path, final String normalizedName, final Li
if (Files.isDirectory(path, options)) {
this.mode = DEFAULT_DIR_MODE;
this.linkFlag = LF_DIR;
-
final int nameLength = normalizedName.length();
if (nameLength == 0 || normalizedName.charAt(nameLength - 1) != '/') {
this.name = normalizedName + "/";
@@ -1874,9 +1867,9 @@ public void setLinkName(final String link) {
}
/**
- * Sets the mode for this entry
+ * Sets the mode for this entry.
*
- * @param mode the mode for this entry
+ * @param mode the mode for this entry.
*/
public void setMode(final int mode) {
this.mode = mode;
diff --git a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveInputStream.java b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveInputStream.java
index af696570e..d0f7d471c 100644
--- a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveInputStream.java
+++ b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveInputStream.java
@@ -103,7 +103,7 @@ public static boolean matches(final byte[] signature, final int length) {
/** True if stream is at EOF. */
private boolean atEof;
- /** Size of the current . */
+ /** Size of the current. */
private long entrySize;
/** How far into the entry the stream is at. */
@@ -132,7 +132,7 @@ public static boolean matches(final byte[] signature, final int length) {
/**
* Constructs a new instance.
*
- * @param inputStream the input stream to use
+ * @param inputStream the input stream to use.
*/
public TarArchiveInputStream(final InputStream inputStream) {
this(inputStream, TarConstants.DEFAULT_BLKSIZE, TarConstants.DEFAULT_RCDSIZE);
@@ -141,7 +141,7 @@ public TarArchiveInputStream(final InputStream inputStream) {
/**
* Constructs a new instance.
*
- * @param inputStream the input stream to use
+ * @param inputStream the input stream to use.
* @param lenient when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to
* {@link TarArchiveEntry#UNKNOWN}. When set to false such illegal fields cause an exception instead.
* @since 1.19
@@ -153,8 +153,8 @@ public TarArchiveInputStream(final InputStream inputStream, final boolean lenien
/**
* Constructs a new instance.
*
- * @param inputStream the input stream to use
- * @param blockSize the block size to use
+ * @param inputStream the input stream to use.
+ * @param blockSize the block size to use.
*/
public TarArchiveInputStream(final InputStream inputStream, final int blockSize) {
this(inputStream, blockSize, TarConstants.DEFAULT_RCDSIZE);
@@ -163,9 +163,9 @@ public TarArchiveInputStream(final InputStream inputStream, final int blockSize)
/**
* Constructs a new instance.
*
- * @param inputStream the input stream to use
- * @param blockSize the block size to use
- * @param recordSize the record size to use
+ * @param inputStream the input stream to use.
+ * @param blockSize the block size to use.
+ * @param recordSize the record size to use.
*/
public TarArchiveInputStream(final InputStream inputStream, final int blockSize, final int recordSize) {
this(inputStream, blockSize, recordSize, null);
@@ -174,10 +174,10 @@ public TarArchiveInputStream(final InputStream inputStream, final int blockSize,
/**
* Constructs a new instance.
*
- * @param inputStream the input stream to use
- * @param blockSize the block size to use
- * @param recordSize the record size to use
- * @param encoding name of the encoding to use for file names
+ * @param inputStream the input stream to use.
+ * @param blockSize the block size to use.
+ * @param recordSize the record size to use.
+ * @param encoding name of the encoding to use for file names.
* @since 1.4
*/
public TarArchiveInputStream(final InputStream inputStream, final int blockSize, final int recordSize, final String encoding) {
@@ -187,10 +187,10 @@ public TarArchiveInputStream(final InputStream inputStream, final int blockSize,
/**
* Constructs a new instance.
*
- * @param inputStream the input stream to use
- * @param blockSize the block size to use
- * @param recordSize the record size to use
- * @param encoding name of the encoding to use for file names
+ * @param inputStream the input stream to use.
+ * @param blockSize the block size to use.
+ * @param recordSize the record size to use.
+ * @param encoding name of the encoding to use for file names.
* @param lenient when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to
* {@link TarArchiveEntry#UNKNOWN}. When set to false such illegal fields cause an exception instead.
* @since 1.19
@@ -206,9 +206,9 @@ public TarArchiveInputStream(final InputStream inputStream, final int blockSize,
/**
* Constructs a new instance.
*
- * @param inputStream the input stream to use
- * @param blockSize the block size to use
- * @param encoding name of the encoding to use for file names
+ * @param inputStream the input stream to use.
+ * @param blockSize the block size to use.
+ * @param encoding name of the encoding to use for file names.
* @since 1.4
*/
public TarArchiveInputStream(final InputStream inputStream, final int blockSize, final String encoding) {
@@ -218,8 +218,8 @@ public TarArchiveInputStream(final InputStream inputStream, final int blockSize,
/**
* Constructs a new instance.
*
- * @param inputStream the input stream to use
- * @param encoding name of the encoding to use for file names
+ * @param inputStream the input stream to use.
+ * @param encoding name of the encoding to use for file names.
* @since 1.4
*/
public TarArchiveInputStream(final InputStream inputStream, final String encoding) {
@@ -256,9 +256,7 @@ public int available() throws IOException {
private void buildSparseInputStreams() throws IOException {
currentSparseInputStreamIndex = -1;
sparseInputStreams = new ArrayList<>();
-
final List<TarArchiveStructSparse> sparseHeaders = currEntry.getOrderedSparseHeaders();
-
// Stream doesn't need to be closed at all as it doesn't use any resources
final InputStream zeroInputStream = new TarArchiveSparseZeroInputStream(); // NOSONAR
// logical offset into the extracted entry
@@ -307,7 +305,7 @@ public boolean canReadEntryData(final ArchiveEntry archiveEntry) {
/**
* Closes this stream. Calls the TarBuffer's close() method.
*
- * @throws IOException on error
+ * @throws IOException on error.
*/
@Override
public void close() throws IOException {
@@ -334,11 +332,11 @@ private void consumeRemainderOfLastBlock() throws IOException {
/**
* For FileInputStream, the skip always return the number you input, so we need the available bytes to determine how many bytes are actually skipped
*
- * @param available available bytes returned by inputStream.available()
- * @param skipped skipped bytes returned by inputStream.skip()
- * @param expected bytes expected to skip
- * @return number of bytes actually skipped
- * @throws IOException if a truncated tar archive is detected
+ * @param available available bytes returned by {@link InputStream#available()}.
+ * @param skipped skipped bytes returned by {@link InputStream#skip()}.
+ * @param expected bytes expected to skip.
+ * @return number of bytes actually skipped.
+ * @throws IOException if a truncated tar archive is detected.
*/
private long getActuallySkipped(final long available, final long skipped, final long expected) throws IOException {
long actuallySkipped = skipped;
@@ -354,7 +352,7 @@ private long getActuallySkipped(final long available, final long skipped, final
/**
* Gets the current TAR Archive Entry that this input stream is processing
*
- * @return The current Archive Entry
+ * @return The current Archive Entry.
*/
public TarArchiveEntry getCurrentEntry() {
return currEntry;
@@ -364,7 +362,7 @@ public TarArchiveEntry getCurrentEntry() {
* Gets the next entry in this tar archive as long name data.
*
* @return The next entry in the archive as long name data, or null.
- * @throws IOException on error
+ * @throws IOException on error.
*
* @deprecated Since 1.29.0 without replacement.
*/
@@ -401,8 +399,8 @@ protected byte[] getLongNameData() throws IOException {
* Handles special records (PAX, GNU long name, sparse, etc.) and applies PAX headers as needed.
* </p>
*
- * @return the next file entry, or {@code null} if there are no more entries
- * @throws IOException if the next entry could not be read or the archive is malformed
+ * @return the next file entry, or {@code null} if there are no more entries.
+ * @throws IOException if the next entry could not be read or the archive is malformed.
*/
@Override
public TarArchiveEntry getNextEntry() throws IOException {
@@ -411,7 +409,6 @@ public TarArchiveEntry getNextEntry() throws IOException {
}
final Map<String, String> paxHeaders = new HashMap<>();
final List<TarArchiveStructSparse> sparseHeaders = new ArrayList<>();
-
// Handle special tar records
boolean lastWasSpecial = false;
do {
@@ -420,35 +417,28 @@ public TarArchiveEntry getNextEntry() throws IOException {
IOUtils.skip(this, Long.MAX_VALUE); // Skip to end of current entry
skipRecordPadding(); // Skip padding to align to the next record
}
-
// Read the next header record
final byte[] headerBuf = getRecord();
if (headerBuf == null) {
// If we encountered special records but no file entry, the archive is malformed
if (lastWasSpecial) {
- throw new ArchiveException(
- "Premature end of tar archive. Didn't find any file entry after GNU or PAX record.");
+ throw new ArchiveException("Premature end of tar archive. Didn't find any file entry after GNU or PAX record.");
}
currEntry = null;
return null; // End of archive
}
-
// Parse the header into a new entry
currEntry = new TarArchiveEntry(globalPaxHeaders, headerBuf, zipEncoding, lenient);
entryOffset = 0;
entrySize = currEntry.getSize();
-
lastWasSpecial = TarUtils.isSpecialTarRecord(currEntry);
if (lastWasSpecial) {
// Handle PAX, GNU long name, or other special records
- TarUtils.handleSpecialTarRecord(
- this, zipEncoding, currEntry, paxHeaders, sparseHeaders, globalPaxHeaders, globalSparseHeaders);
+ TarUtils.handleSpecialTarRecord(this, zipEncoding, currEntry, paxHeaders, sparseHeaders, globalPaxHeaders, globalSparseHeaders);
}
} while (lastWasSpecial);
-
// Apply global and local PAX headers
TarUtils.applyPaxHeadersToEntry(currEntry, paxHeaders, sparseHeaders, globalPaxHeaders, globalSparseHeaders);
-
// Handle sparse files
if (currEntry.isSparse()) {
if (currEntry.isOldGNUSparse()) {
@@ -460,12 +450,10 @@ public TarArchiveEntry getNextEntry() throws IOException {
// sparse input streams using these sparse headers
buildSparseInputStreams();
}
-
// Ensure directory names end with a slash
if (currEntry.isDirectory() && !currEntry.getName().endsWith("/")) {
currEntry.setName(currEntry.getName() + "/");
}
-
// Update entry size in case it changed due to PAX headers
entrySize = currEntry.getSize();
return currEntry;
@@ -477,7 +465,7 @@ public TarArchiveEntry getNextEntry() throws IOException {
* the archive, null will be returned to indicate that the end of the archive has been reached.
*
* @return The next TarEntry in the archive, or null.
- * @throws IOException on error
+ * @throws IOException on error.
* @deprecated Use {@link #getNextEntry()}.
*/
@Deprecated
@@ -494,7 +482,7 @@ public TarArchiveEntry getNextTarEntry() throws IOException {
* </p>
*
* @return The next header in the archive, or null.
- * @throws IOException on error
+ * @throws IOException on error.
*/
private byte[] getRecord() throws IOException {
byte[] headerBuf = readRecord();
@@ -533,7 +521,7 @@ private boolean isDirectory() {
* Tests if an archive record indicate End of Archive. End of 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
+ * @return true if the record data is an End of Archive.
*/
protected boolean isEOFRecord(final byte[] record) {
return record == null || ArchiveUtils.isArrayZero(record, getRecordSize());
@@ -551,7 +539,7 @@ public synchronized void mark(final int markLimit) {
/**
* Since we do not support marking just yet, we return false.
*
- * @return false.
+ * @return Always false.
*/
@Override
public boolean markSupported() {
@@ -607,7 +595,7 @@ public int read(final byte[] buf, final int offset, int numToRead) throws IOExce
/**
* Adds the sparse chunks from the current entry to the sparse chunks, including any additional sparse entries following the current entry.
*
- * @throws IOException on error
+ * @throws IOException on error.
*/
private void readOldGNUSparse() throws IOException {
if (currEntry.isExtended()) {
@@ -630,7 +618,7 @@ private void readOldGNUSparse() throws IOException {
* Reads a record from the input stream and return the data.
*
* @return The record data or null if EOF has been hit.
- * @throws IOException on error
+ * @throws IOException on error.
*/
protected byte[] readRecord() throws IOException {
final int readCount = IOUtils.readFully(in, recordBuffer);
@@ -651,7 +639,7 @@ protected byte[] readRecord() throws IOException {
* @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
+ * @throws IOException on error.
*/
private int readSparse(final byte[] buf, final int offset, final int numToRead) throws IOException {
// if there are no actual input streams, just read from the original input stream
@@ -720,7 +708,7 @@ protected final void setCurrentEntry(final TarArchiveEntry currEntry) {
*
* @param n the number of bytes to be skipped.
* @return the actual number of bytes skipped.
- * @throws IOException if a truncated tar archive is detected or some other I/O error occurs
+ * @throws IOException if a truncated tar archive is detected or some other I/O error occurs.
*/
@Override
public long skip(final long n) throws IOException {
@@ -747,7 +735,7 @@ public long skip(final long n) throws IOException {
/**
* The last record block should be written at the full size, so skip any additional space used to fill a record after an entry.
*
- * @throws IOException if a truncated tar archive is detected
+ * @throws IOException if a truncated tar archive is detected.
*/
private void skipRecordPadding() throws IOException {
if (!isDirectory() && this.entrySize > 0 && this.entrySize % getRecordSize() != 0) {
@@ -764,8 +752,8 @@ private void skipRecordPadding() throws IOException {
* Skip n bytes from current input stream, if the current input stream doesn't have enough data to skip, jump to the next input stream and skip the rest
* bytes, keep doing this until total n bytes are skipped or the input streams are all skipped
*
- * @param n bytes of data to skip
- * @return actual bytes of data skipped
+ * @param n bytes of data to skip.
+ * @return actual bytes of data skipped.
* @throws IOException if an I/O error occurs.
*/
private long skipSparse(final long n) throws IOException {
diff --git a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveOutputStream.java b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveOutputStream.java
index bfaf7e89d..a55e9f1fc 100644
--- a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveOutputStream.java
+++ b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveOutputStream.java
@@ -132,7 +132,7 @@ public class TarArchiveOutputStream extends ArchiveOutputStream<TarArchiveEntry>
* Uses a block size of 512 bytes.
* </p>
*
- * @param os the output stream to use
+ * @param os the output stream to use.
*/
public TarArchiveOutputStream(final OutputStream os) {
this(os, BLOCK_SIZE_UNSPECIFIED);
@@ -141,7 +141,7 @@ public TarArchiveOutputStream(final OutputStream os) {
/**
* Constructs a new instance.
*
- * @param os the output stream to use
+ * @param os the output stream to use.
* @param blockSize the block size to use. Must be a multiple of 512 bytes.
*/
public TarArchiveOutputStream(final OutputStream os, final int blockSize) {
@@ -151,8 +151,8 @@ public TarArchiveOutputStream(final OutputStream os, final int blockSize) {
/**
* Constructs a new instance.
*
- * @param os the output stream to use
- * @param blockSize the block size to use
+ * @param os the output stream to use.
+ * @param blockSize the block size to use.
* @param recordSize the record size to use. Must be 512 bytes.
* @deprecated recordSize must always be 512 bytes. An IllegalArgumentException will be thrown if any other value is used
*/
@@ -164,10 +164,10 @@ public TarArchiveOutputStream(final OutputStream os, final int blockSize, final
/**
* Constructs a new instance.
*
- * @param os the output stream to use
+ * @param os the output stream to use.
* @param blockSize the block size to use . Must be a multiple of 512 bytes.
* @param recordSize the record size to use. Must be 512 bytes.
- * @param encoding name of the encoding to use for file names
+ * @param encoding name of the encoding to use for file names.
* @since 1.4
* @deprecated recordSize must always be 512 bytes. An IllegalArgumentException will be thrown if any other value is used.
*/
@@ -183,9 +183,9 @@ public TarArchiveOutputStream(final OutputStream os, final int blockSize, final
/**
* Constructs a new instance.
*
- * @param os the output stream to use
+ * @param os the output stream to use.
* @param blockSize the block size to use. Must be a multiple of 512 bytes.
- * @param charset name of the encoding to use for file names
+ * @param charset name of the encoding to use for file names.
* @since 1.4
*/
public TarArchiveOutputStream(final OutputStream os, final int blockSize, final String charset) {
@@ -196,14 +196,12 @@ public TarArchiveOutputStream(final OutputStream os, final int blockSize, final
} else {
realBlockSize = blockSize;
}
-
if (realBlockSize <= 0 || realBlockSize % RECORD_SIZE != 0) {
throw new IllegalArgumentException("Block size must be a multiple of 512 bytes. Attempt to use set size of " + blockSize);
}
this.out = new FixedLengthBlockOutputStream(countingOut = new CountingOutputStream(os), RECORD_SIZE);
this.charsetName = Charsets.toCharset(charset).name();
this.zipEncoding = ZipEncodingHelper.getZipEncoding(charset);
-
this.recordBuf = new byte[RECORD_SIZE];
this.recordsPerBlock = realBlockSize / RECORD_SIZE;
}
@@ -215,8 +213,8 @@ public TarArchiveOutputStream(final OutputStream os, final int blockSize, final
* Uses a block size of 512 bytes.
* </p>
*
- * @param os the output stream to use
- * @param charset name of the encoding to use for file names
+ * @param os the output stream to use.
+ * @param charset name of the encoding to use for file names.
* @since 1.4
*/
public TarArchiveOutputStream(final OutputStream os, final String charset) {
@@ -389,7 +387,7 @@ private void failForBigNumberWithPosixMessage(final String field, final long val
* An archive consists of a series of file entries terminated by an end-of-archive entry, which consists of two 512 blocks of zero bytes. POSIX.1 requires
* two EOF records, like some other implementations.
*
- * @throws IOException on error
+ * @throws IOException on error.
*/
@Override
public void finish() throws IOException {
@@ -439,14 +437,14 @@ public int getRecordSize() {
* </ul>
* </p>
*
- * @param entry entry the name belongs to
- * @param name the name to write
- * @param paxHeaders current map of pax headers
- * @param paxHeaderName name of the pax header to write
- * @param linkType type of the GNU entry to write
- * @param fieldName the name of the field
+ * @param entry entry the name belongs to.
+ * @param name the name to write.
+ * @param paxHeaders current map of pax headers.
+ * @param paxHeaderName name of the pax header to write.
+ * @param linkType type of the GNU entry to write.
+ * @param fieldName the name of the field.
* @throws IllegalArgumentException if the {@link TarArchiveOutputStream#longFileMode} equals {@link TarArchiveOutputStream#LONGFILE_ERROR} and the file
- * name is too long
+ * name is too long.
* @return whether a pax header has been written.
*/
private boolean handleLongName(final TarArchiveEntry entry, final String name, final Map<String, String> paxHeaders, final String paxHeaderName,
@@ -520,32 +518,25 @@ public void putArchiveEntry(final TarArchiveEntry archiveEntry) throws IOExcepti
final String linkName = archiveEntry.getLinkName();
final boolean paxHeaderContainsLinkPath = linkName != null && !linkName.isEmpty()
&& handleLongName(archiveEntry, linkName, paxHeaders, "linkpath", TarConstants.LF_GNUTYPE_LONGLINK, "link name");
-
if (bigNumberMode == BIGNUMBER_POSIX) {
addPaxHeadersForBigNumbers(paxHeaders, archiveEntry);
} else if (bigNumberMode != BIGNUMBER_STAR) {
failForBigNumbers(archiveEntry);
}
-
if (addPaxHeadersForNonAsciiNames && !paxHeaderContainsPath && !ASCII.canEncode(entryName)) {
paxHeaders.put("path", entryName);
}
-
if (addPaxHeadersForNonAsciiNames && !paxHeaderContainsLinkPath && (archiveEntry.isLink() || archiveEntry.isSymbolicLink())
&& !ASCII.canEncode(linkName)) {
paxHeaders.put("linkpath", linkName);
}
paxHeaders.putAll(archiveEntry.getExtraPaxHeaders());
-
if (!paxHeaders.isEmpty()) {
writePaxHeaders(archiveEntry, entryName, paxHeaders);
}
-
archiveEntry.writeEntryHeader(recordBuf, zipEncoding, bigNumberMode == BIGNUMBER_STAR);
writeRecord(recordBuf);
-
currBytes = 0;
-
if (archiveEntry.isDirectory()) {
currSize = 0;
} else {
@@ -581,7 +572,7 @@ public void setBigNumberMode(final int bigNumberMode) {
* Sets the long file mode. This can be LONGFILE_ERROR(0), LONGFILE_TRUNCATE(1), LONGFILE_GNU(2) or LONGFILE_POSIX(3). This specifies the treatment of long
* file names (names >= TarConstants.NAMELEN). Default is LONGFILE_ERROR.
*
- * @param longFileMode the mode to use
+ * @param longFileMode the mode to use.
*/
public void setLongFileMode(final int longFileMode) {
this.longFileMode = longFileMode;
@@ -672,13 +663,12 @@ void writePaxHeaders(final TarArchiveEntry entry, final String entryName, final
* Writes an archive record to the archive.
*
* @param record The record data to write to the archive.
- * @throws IOException on error
+ * @throws IOException on error.
*/
private void writeRecord(final byte[] record) throws IOException {
if (record.length != RECORD_SIZE) {
throw new ArchiveException("Record to write has length %,d which is not the record size of %,d", record.length, RECORD_SIZE);
}
-
out.write(record);
recordsWritten++;
}
diff --git a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveSparseEntry.java b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveSparseEntry.java
index 05ae43d12..f4cff02f6 100644
--- a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveSparseEntry.java
+++ b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveSparseEntry.java
@@ -61,7 +61,7 @@ public class TarArchiveSparseEntry implements TarConstants {
* Constructs an entry from an archive's header bytes. File is set to null.
*
* @param headerBuf The header bytes from a tar archive entry.
- * @throws IOException on unknown format
+ * @throws IOException on unknown format.
*/
public TarArchiveSparseEntry(final byte[] headerBuf) throws IOException {
int offset = 0;
diff --git a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveSparseZeroInputStream.java b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveSparseZeroInputStream.java
index f22a7aac2..513ed0722 100644
--- a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveSparseZeroInputStream.java
+++ b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveSparseZeroInputStream.java
@@ -28,7 +28,7 @@ final class TarArchiveSparseZeroInputStream extends InputStream {
/**
* Returns 0.
*
- * @return 0.
+ * @return Always 0.
*/
@Override
public int read() {
@@ -38,8 +38,8 @@ public int read() {
/**
* Returns the input.
*
- * @param n bytes to skip
- * @return bytes actually skipped
+ * @param n a value to return.
+ * @return the input.
*/
@Override
public long skip(final long n) {
diff --git a/src/main/java/org/apache/commons/compress/archivers/tar/TarFile.java b/src/main/java/org/apache/commons/compress/archivers/tar/TarFile.java
index 8143921c9..b92a6459f 100644
--- a/src/main/java/org/apache/commons/compress/archivers/tar/TarFile.java
+++ b/src/main/java/org/apache/commons/compress/archivers/tar/TarFile.java
@@ -72,14 +72,12 @@ protected int read(final long pos, final ByteBuffer buf) throws IOException {
if (entryOffset >= entry.getRealSize()) {
return -1;
}
-
final int totalRead;
if (entry.isSparse()) {
totalRead = readSparse(entryOffset, buf, buf.limit());
} else {
totalRead = readArchive(pos, buf);
}
-
if (totalRead == -1) {
if (buf.array().length > 0) {
throw new ArchiveException("Truncated TAR archive");
@@ -103,30 +101,25 @@ private int readSparse(final long pos, final ByteBuffer buf, final int numToRead
if (entrySparseInputStreams == null || entrySparseInputStreams.isEmpty()) {
return readArchive(entry.getDataOffset() + pos, buf);
}
-
if (currentSparseInputStreamIndex >= entrySparseInputStreams.size()) {
return -1;
}
-
final InputStream currentInputStream = entrySparseInputStreams.get(currentSparseInputStreamIndex);
final byte[] bufArray = new byte[numToRead];
final int readLen = currentInputStream.read(bufArray);
if (readLen != -1) {
buf.put(bufArray, 0, readLen);
}
-
// if the current input stream is the last input stream,
// just return the number of bytes read from current input stream
if (currentSparseInputStreamIndex == entrySparseInputStreams.size() - 1) {
return readLen;
}
-
// if EOF of current input stream is meet, open a new input stream and recursively call read
if (readLen == -1) {
currentSparseInputStreamIndex++;
return readSparse(pos, buf, numToRead);
}
-
// if the rest data of current input stream is not long enough, open a new input stream
// and recursively call read
if (readLen < numToRead) {
@@ -135,10 +128,8 @@ private int readSparse(final long pos, final ByteBuffer buf, final int numToRead
if (readLenOfNext == -1) {
return readLen;
}
-
return readLen + readLenOfNext;
}
-
// if the rest data of current input stream is enough(which means readLen == len), just return readLen
return readLen;
}
@@ -161,17 +152,21 @@ private int readSparse(final long pos, final ByteBuffer buf, final int numToRead
private final ByteBuffer recordBuffer;
- // the global sparse headers, this is only used in PAX Format 0.X
+ /**
+ * The global sparse headers, this is only used in PAX Format 0.X.
+ */
private final List<TarArchiveStructSparse> globalSparseHeaders = new ArrayList<>();
private boolean eof;
/**
- * The meta-data about the current entry
+ * The meta-data about the current entry.
*/
private TarArchiveEntry currEntry;
- // the global PAX header
+ /**
+ * The global PAX header.
+ */
private final Map<String, String> globalPaxHeaders = new HashMap<>();
private final Map<String, List<InputStream>> sparseInputStreams = new HashMap<>();
@@ -179,8 +174,8 @@ private int readSparse(final long pos, final ByteBuffer buf, final int numToRead
/**
* Constructor for TarFile.
*
- * @param content the content to use
- * @throws IOException when reading the tar archive fails
+ * @param content the content to use.
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final byte[] content) throws IOException {
this(new SeekableInMemoryByteChannel(content));
@@ -189,10 +184,10 @@ public TarFile(final byte[] content) throws IOException {
/**
* Constructor for TarFile.
*
- * @param content the content to use
+ * @param content the content to use.
* @param lenient when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to
* {@link TarArchiveEntry#UNKNOWN}. When set to false such illegal fields cause an exception instead.
- * @throws IOException when reading the tar archive fails
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final byte[] content, final boolean lenient) throws IOException {
this(new SeekableInMemoryByteChannel(content), TarConstants.DEFAULT_BLKSIZE, TarConstants.DEFAULT_RCDSIZE, null, lenient);
@@ -201,9 +196,9 @@ public TarFile(final byte[] content, final boolean lenient) throws IOException {
/**
* Constructor for TarFile.
*
- * @param content the content to use
- * @param encoding the encoding to use
- * @throws IOException when reading the tar archive fails
+ * @param content the content to use.
+ * @param encoding the encoding to use.
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final byte[] content, final String encoding) throws IOException {
this(new SeekableInMemoryByteChannel(content), TarConstants.DEFAULT_BLKSIZE, TarConstants.DEFAULT_RCDSIZE, encoding, false);
@@ -212,8 +207,8 @@ public TarFile(final byte[] content, final String encoding) throws IOException {
/**
* Constructor for TarFile.
*
- * @param archive the file of the archive to use
- * @throws IOException when reading the tar archive fails
+ * @param archive the file of the archive to use.
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final File archive) throws IOException {
this(archive.toPath());
@@ -222,10 +217,10 @@ public TarFile(final File archive) throws IOException {
/**
* Constructor for TarFile.
*
- * @param archive the file of the archive to use
+ * @param archive the file of the archive to use.
* @param lenient when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to
* {@link TarArchiveEntry#UNKNOWN}. When set to false such illegal fields cause an exception instead.
- * @throws IOException when reading the tar archive fails
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final File archive, final boolean lenient) throws IOException {
this(archive.toPath(), lenient);
@@ -234,9 +229,9 @@ public TarFile(final File archive, final boolean lenient) throws IOException {
/**
* Constructor for TarFile.
*
- * @param archive the file of the archive to use
- * @param encoding the encoding to use
- * @throws IOException when reading the tar archive fails
+ * @param archive the file of the archive to use.
+ * @param encoding the encoding to use.
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final File archive, final String encoding) throws IOException {
this(archive.toPath(), encoding);
@@ -245,8 +240,8 @@ public TarFile(final File archive, final String encoding) throws IOException {
/**
* Constructor for TarFile.
*
- * @param archivePath the path of the archive to use
- * @throws IOException when reading the tar archive fails
+ * @param archivePath the path of the archive to use.
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final Path archivePath) throws IOException {
this(Files.newByteChannel(archivePath), TarConstants.DEFAULT_BLKSIZE, TarConstants.DEFAULT_RCDSIZE, null, false);
@@ -255,10 +250,10 @@ public TarFile(final Path archivePath) throws IOException {
/**
* Constructor for TarFile.
*
- * @param archivePath the path of the archive to use
+ * @param archivePath the path of the archive to use.
* @param lenient when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to
* {@link TarArchiveEntry#UNKNOWN}. When set to false such illegal fields cause an exception instead.
- * @throws IOException when reading the tar archive fails
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final Path archivePath, final boolean lenient) throws IOException {
this(Files.newByteChannel(archivePath), TarConstants.DEFAULT_BLKSIZE, TarConstants.DEFAULT_RCDSIZE, null, lenient);
@@ -267,9 +262,9 @@ public TarFile(final Path archivePath, final boolean lenient) throws IOException
/**
* Constructor for TarFile.
*
- * @param archivePath the path of the archive to use
- * @param encoding the encoding to use
- * @throws IOException when reading the tar archive fails
+ * @param archivePath the path of the archive to use.
+ * @param encoding the encoding to use.
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final Path archivePath, final String encoding) throws IOException {
this(Files.newByteChannel(archivePath), TarConstants.DEFAULT_BLKSIZE, TarConstants.DEFAULT_RCDSIZE, encoding, false);
@@ -278,8 +273,8 @@ public TarFile(final Path archivePath, final String encoding) throws IOException
/**
* Constructor for TarFile.
*
- * @param content the content to use
- * @throws IOException when reading the tar archive fails
+ * @param content the content to use.
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final SeekableByteChannel content) throws IOException {
this(content, TarConstants.DEFAULT_BLKSIZE, TarConstants.DEFAULT_RCDSIZE, null, false);
@@ -288,13 +283,13 @@ public TarFile(final SeekableByteChannel content) throws IOException {
/**
* Constructor for TarFile.
*
- * @param archive the seekable byte channel to use
- * @param blockSize the blocks size to use
- * @param recordSize the record size to use
- * @param encoding the encoding to use
+ * @param archive the seekable byte channel to use.
+ * @param blockSize the blocks size to use.
+ * @param recordSize the record size to use.
+ * @param encoding the encoding to use.
* @param lenient when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to
* {@link TarArchiveEntry#UNKNOWN}. When set to false such illegal fields cause an exception instead.
- * @throws IOException when reading the tar archive fails
+ * @throws IOException when reading the tar archive fails.
*/
public TarFile(final SeekableByteChannel archive, final int blockSize, final int recordSize, final String encoding, final boolean lenient)
throws IOException {
@@ -304,7 +299,6 @@ public TarFile(final SeekableByteChannel archive, final int blockSize, final int
this.recordBuffer = ByteBuffer.allocate(this.recordSize);
this.blockSize = blockSize;
this.lenient = lenient;
-
TarArchiveEntry entry;
while ((entry = getNextTarEntry()) != null) {
entries.add(entry);
@@ -368,9 +362,9 @@ private void consumeRemainderOfLastBlock() throws IOException {
}
/**
- * Gets all TAR Archive Entries from the TarFile
+ * Gets all TAR Archive Entries from the TarFile.
*
- * @return All entries from the tar file
+ * @return All entries from the tar file.
*/
public List<TarArchiveEntry> getEntries() {
return new ArrayList<>(entries);
@@ -379,8 +373,8 @@ public List<TarArchiveEntry> getEntries() {
/**
* Gets the input stream for the provided Tar Archive Entry.
*
- * @param entry Entry to get the input stream from
- * @return Input stream of the provided entry
+ * @param entry Entry to get the input stream from.
+ * @return Input stream of the provided entry.
* @throws IOException Corrupted TAR archive. Can't read entry.
*/
public InputStream getInputStream(final TarArchiveEntry entry) throws IOException {
@@ -405,7 +399,6 @@ private TarArchiveEntry getNextTarEntry() throws IOException {
}
final Map<String, String> paxHeaders = new HashMap<>();
final List<TarArchiveStructSparse> sparseHeaders = new ArrayList<>();
-
// Handle special tar records
boolean lastWasSpecial = false;
do {
@@ -415,40 +408,28 @@ private TarArchiveEntry getNextTarEntry() throws IOException {
throwExceptionIfPositionIsNotInArchive();
skipRecordPadding();
}
-
// Read the next header record
final ByteBuffer headerBuf = getRecord();
if (headerBuf == null) {
// If we encountered special records but no file entry, the archive is malformed
if (lastWasSpecial) {
- throw new ArchiveException(
- "Premature end of tar archive. Didn't find any file entry after GNU or PAX record.");
+ throw new ArchiveException("Premature end of tar archive. Didn't find any file entry after GNU or PAX record.");
}
currEntry = null;
return null; // End of archive
}
-
// Parse the header into a new entry
final long position = archive.position();
currEntry = new TarArchiveEntry(globalPaxHeaders, headerBuf.array(), zipEncoding, lenient, position);
-
lastWasSpecial = TarUtils.isSpecialTarRecord(currEntry);
if (lastWasSpecial) {
// Handle PAX, GNU long name, or other special records
- TarUtils.handleSpecialTarRecord(
- getInputStream(currEntry),
- zipEncoding,
- currEntry,
- paxHeaders,
- sparseHeaders,
- globalPaxHeaders,
+ TarUtils.handleSpecialTarRecord(getInputStream(currEntry), zipEncoding, currEntry, paxHeaders, sparseHeaders, globalPaxHeaders,
globalSparseHeaders);
}
} while (lastWasSpecial);
-
// Apply global and local PAX headers
TarUtils.applyPaxHeadersToEntry(currEntry, paxHeaders, sparseHeaders, globalPaxHeaders, globalSparseHeaders);
-
// Handle sparse files
if (currEntry.isSparse()) {
if (currEntry.isOldGNUSparse()) {
@@ -461,12 +442,10 @@ private TarArchiveEntry getNextTarEntry() throws IOException {
// sparse input streams using these sparse headers
buildSparseInputStreams();
}
-
// Ensure directory names end with a slash
if (currEntry.isDirectory() && !currEntry.getName().endsWith("/")) {
currEntry.setName(currEntry.getName() + "/");
}
-
return currEntry;
}
@@ -529,7 +508,6 @@ private void readOldGNUSparse() throws IOException {
currEntry.setDataOffset(currEntry.getDataOffset() + recordSize);
} while (entry.isExtended());
}
-
// sparse headers are all done reading, we need to build
// sparse input streams using these sparse headers
buildSparseInputStreams();
diff --git a/src/main/java/org/apache/commons/compress/archivers/tar/TarUtils.java b/src/main/java/org/apache/commons/compress/archivers/tar/TarUtils.java
index b495335e1..175248a53 100644
--- a/src/main/java/org/apache/commons/compress/archivers/tar/TarUtils.java
+++ b/src/main/java/org/apache/commons/compress/archivers/tar/TarUtils.java
@@ -85,19 +85,15 @@ public ByteBuffer encode(final String name) {
/**
* Applies the PAX headers and sparse headers to the given tar entry.
*
- * @param entry the tar entry to handle
- * @param paxHeaders per file PAX headers
- * @param sparseHeaders per file sparse headers
- * @param globalPaxHeaders global PAX headers
+ * @param entry the tar entry to handle
+ * @param paxHeaders per file PAX headers
+ * @param sparseHeaders per file sparse headers
+ * @param globalPaxHeaders global PAX headers
* @param globalSparseHeaders global sparse headers
* @throws IOException if an I/O error occurs while reading the entry
*/
- static void applyPaxHeadersToEntry(
- final TarArchiveEntry entry,
- final Map<String, String> paxHeaders,
- final List<TarArchiveStructSparse> sparseHeaders,
- final Map<String, String> globalPaxHeaders,
- final List<TarArchiveStructSparse> globalSparseHeaders) throws IOException {
+ static void applyPaxHeadersToEntry(final TarArchiveEntry entry, final Map<String, String> paxHeaders, final List<TarArchiveStructSparse> sparseHeaders,
+ final Map<String, String> globalPaxHeaders, final List<TarArchiveStructSparse> globalSparseHeaders) throws IOException {
// Apply PAX headers to the entry
entry.updateEntryFromPaxHeaders(globalPaxHeaders);
entry.updateEntryFromPaxHeaders(paxHeaders);