This is an automated email from the ASF dual-hosted git repository. peterlee pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-compress.git
commit 543ac95593bcad8d656e27be1e2ce2e48cd26b4a Author: theobisproject <theobisproj...@gmail.com> AuthorDate: Fri Dec 25 21:37:14 2020 +0100 COMPRESS-540: Javadoc enhancement - Add thread safety information for input streams - Use consistent capitalization and punctuation in Javadoc - Use html tags for better Javadoc formatting --- .../commons/compress/archivers/tar/TarArchiveEntry.java | 16 ++++++++-------- .../apache/commons/compress/archivers/tar/TarFile.java | 14 +++++++++----- .../commons/compress/utils/BoundedNIOInputStream.java | 1 + .../utils/BoundedSeekableByteChannelInputStream.java | 1 + 4 files changed, 19 insertions(+), 13 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 37e76c9..9153a5d 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 @@ -556,14 +556,14 @@ public class TarArchiveEntry implements ArchiveEntry, TarConstants, EntryStreamO /** * Construct an entry from an archive's header bytes for random access tar. File is set to null. - * @param headerBuf The header bytes from a tar archive entry. - * @param encoding encoding to use for file names + * @param headerBuf the header bytes from a tar archive entry. + * @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. - * @param dataOffset Position of the entry data in the random access file + * @param dataOffset position of the entry data in the random access file. * @since 1.21 - * @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. */ public TarArchiveEntry(final byte[] headerBuf, final ZipEncoding encoding, final boolean lenient, final long dataOffset) throws IOException { @@ -869,7 +869,7 @@ public class TarArchiveEntry implements ArchiveEntry, TarConstants, EntryStreamO * <p>This method is only useful for entries created from a {@code * File} or {@code Path} but not for entries read from an archive.</p> * - * @return This entry's file or null if the entry was not created from a file. + * @return this entry's file or null if the entry was not created from a file. */ public File getFile() { if (file == null) { @@ -884,7 +884,7 @@ public class TarArchiveEntry implements ArchiveEntry, TarConstants, EntryStreamO * <p>This method is only useful for entries created from a {@code * File} or {@code Path} but not for entries read from an archive.</p> * - * @return This entry's file or null if the entry was not created from a file. + * @return this entry's file or null if the entry was not created from a file. * @since 1.21 */ public Path getPath() { @@ -1213,7 +1213,7 @@ public class TarArchiveEntry implements ArchiveEntry, TarConstants, EntryStreamO /** * Set the offset of the data for the tar entry. - * @param dataOffset the position of the data in the tar + * @param dataOffset the position of the data in the tar. * @since 1.21 */ public void setDataOffset(final long dataOffset) { 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 f512d29..dc4ab20 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 @@ -332,7 +332,7 @@ public class TarFile implements Closeable { * When reading from the non-zero input streams, the data is actually read from the original input stream. * The size of each input stream is introduced by the sparse headers. * - * NOTE : Some all-zero input streams and non-zero input streams have the size of 0. We DO NOT store the + * @implNote Some all-zero input streams and non-zero input streams have the size of 0. We DO NOT store the * 0 size input streams because they are meaningless. */ private void buildSparseInputStreams() throws IOException { @@ -398,24 +398,28 @@ public class TarFile implements Closeable { } /** + * <p> * For PAX Format 0.0, the sparse headers(GNU.sparse.offset and GNU.sparse.numbytes) * may appear multi times, and they look like: - * + * <pre> * GNU.sparse.size=size * GNU.sparse.numblocks=numblocks * repeat numblocks times * GNU.sparse.offset=offset * GNU.sparse.numbytes=numbytes * end repeat + * </pre> * - * + * <p> * For PAX Format 0.1, the sparse headers are stored in a single variable : GNU.sparse.map - * + * <pre> * GNU.sparse.map * Map of non-null data chunks. It is a string consisting of comma-separated values "offset,size[,offset-1,size-1...]" + * </pre> * - * + * <p> * For PAX Format 1.X: + * <br> * The sparse map itself is stored in the file data block, preceding the actual file data. * It consists of a series of decimal numbers delimited by newlines. The map is padded with nulls to the nearest block boundary. * The first number gives the number of entries in the map. Following are map entries, each one consisting of two numbers diff --git a/src/main/java/org/apache/commons/compress/utils/BoundedNIOInputStream.java b/src/main/java/org/apache/commons/compress/utils/BoundedNIOInputStream.java index 6f8015a..2a692c0 100644 --- a/src/main/java/org/apache/commons/compress/utils/BoundedNIOInputStream.java +++ b/src/main/java/org/apache/commons/compress/utils/BoundedNIOInputStream.java @@ -23,6 +23,7 @@ import java.nio.ByteBuffer; /** * NIO backed bounded input stream for reading a predefined amount of data from. + * @ThreadSafe this base class is thread safe but implementations must not be. * @since 1.21 */ public abstract class BoundedNIOInputStream extends InputStream { diff --git a/src/main/java/org/apache/commons/compress/utils/BoundedSeekableByteChannelInputStream.java b/src/main/java/org/apache/commons/compress/utils/BoundedSeekableByteChannelInputStream.java index f8499bd..9da4a34 100644 --- a/src/main/java/org/apache/commons/compress/utils/BoundedSeekableByteChannelInputStream.java +++ b/src/main/java/org/apache/commons/compress/utils/BoundedSeekableByteChannelInputStream.java @@ -24,6 +24,7 @@ import java.nio.channels.SeekableByteChannel; /** * InputStream that delegates requests to the underlying SeekableByteChannel, making sure that only bytes from a certain * range can be read. + * @ThreadSafe * @since 1.21 */ public class BoundedSeekableByteChannelInputStream extends BoundedNIOInputStream {