(commons-compress) branch master updated: Improve Javadoc of `ZipArchiveEntry` (#769)

[ggregory]

This is an automated email from the ASF dual-hosted git repository.

garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-compress.git


The following commit(s) were added to refs/heads/master by this push:
     new acc479f95 Improve Javadoc of `ZipArchiveEntry` (#769)
acc479f95 is described below

commit acc479f957e67ccaeaf17e4cf6d590480450ede4
Author: Piotr P. Karwasz <pkarwasz-git...@apache.org>
AuthorDate: Tue Apr 28 21:03:13 2026 +0200

    Improve Javadoc of `ZipArchiveEntry` (#769)
    
    This change improves the Javadoc of those methods in `ZipArchiveEntry` that 
rely on `getExternalAttributes()`: `getUnixMode()` and `isUnixSymlink()`. These 
methods are only filled by parsers that can read the central directory and 
therefore don't work with `ZipArchiveInputStream`.
---
 .../commons/compress/archivers/zip/ZipArchiveEntry.java  | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git 
a/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntry.java 
b/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntry.java
index cff1325cf..6753172f8 100644
--- 
a/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntry.java
+++ 
b/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntry.java
@@ -687,8 +687,8 @@ public long getDiskNumberStart() {
      * Gets the external file attributes.
      *
      * <p>
-     * <strong>Note</strong>: {@link ZipArchiveInputStream} is unable to fill 
this field, you must use {@link ZipFile} if you want to read entries using this
-     * attribute.
+     * <strong>Note:</strong> This field is stored in the central directory 
only and is not populated when reading entries via
+     * {@link ZipArchiveInputStream}; use {@link ZipFile} instead.
      * </p>
      *
      * @return the external file attributes.
@@ -963,7 +963,12 @@ public long getTime() {
     /**
      * Gets the Unix permission.
      *
-     * @return the Unix permissions.
+     * <p>
+     * <strong>Note:</strong> This method relies on {@link 
#getExternalAttributes()}, which is not populated when reading entries via
+     * {@link ZipArchiveInputStream}; use {@link ZipFile} instead.
+     * </p>
+     *
+     * @return the Unix permissions, or 0 if the platform is not {@link 
#PLATFORM_UNIX}.
      */
     public int getUnixMode() {
         return platform != PLATFORM_UNIX ? 0 : (int) (getExternalAttributes() 
>> SHORT_SHIFT & SHORT_MASK);
@@ -1072,6 +1077,11 @@ public boolean isStreamContiguous() {
     /**
      * Tests whether this entry represents a Unix symlink, in which case the 
entry's content contains the target path for the symlink.
      *
+     * <p>
+     * <strong>Note:</strong> This method relies on {@link 
#getExternalAttributes()}, which is not populated when reading entries via
+     * {@link ZipArchiveInputStream}; use {@link ZipFile} instead.
+     * </p>
+     *
      * @return true if the entry represents a Unix symlink, false otherwise.
      * @since 1.5
      */