Package org.apache.commons.compress.archivers.zip

Class ZipArchiveEntry

  • All Implemented Interfaces:
    java.lang.Cloneable, ArchiveEntry, EntryStreamOffsets
    Direct Known Subclasses:
    JarArchiveEntry, ZipFile.Entry
    public class ZipArchiveEntry
extends java.util.zip.ZipEntry
implements ArchiveEntry, EntryStreamOffsets
    Extension that adds better handling of extra fields and provides access to the internal and external file attributes.

    The extra data is expected to follow the recommendation of APPNOTE.TXT:

    • the extra byte array consists of a sequence of extra fields
    • each extra fields starts by a two byte header id followed by a two byte sequence holding the length of the remainder of data.

    Any extra data that cannot be parsed by the rules above will be consumed as "unparseable" extra data and treated differently by the methods of this class. Versions prior to Apache Commons Compress 1.1 would have thrown an exception if any attempt was made to read or write extra data not conforming to the recommendation.

    • Constructor Detail

      • ZipArchiveEntry

        protected ZipArchiveEntry()

      • ZipArchiveEntry

        public ZipArchiveEntry​(java.io.File inputFile,
                       java.lang.String entryName)
        Creates a new ZIP entry taking some information from the given file and using the provided name.

        The name will be adjusted to end with a forward slash "/" if the file is a directory. If the file is not a directory a potential trailing forward slash will be stripped from the entry name.

        Parameters:
        inputFile - file to create the entry from
        entryName - name of the entry

      • ZipArchiveEntry

        private ZipArchiveEntry​(java.util.function.Function<ZipShort,​ZipExtraField> extraFieldFactory,
                        java.io.File inputFile,
                        java.lang.String entryName)
        Creates a new ZIP entry taking some information from the given file and using the provided name.

        The name will be adjusted to end with a forward slash "/" if the file is a directory. If the file is not a directory a potential trailing forward slash will be stripped from the entry name.

        Parameters:
        extraFieldFactory - custom lookup factory for extra fields or null
        inputFile - file to create the entry from
        entryName - name of the entry

      • ZipArchiveEntry

        private ZipArchiveEntry​(java.util.function.Function<ZipShort,​ZipExtraField> extraFieldFactory,
                        java.nio.file.Path inputPath,
                        java.lang.String entryName,
                        java.nio.file.LinkOption... options)
                 throws java.io.IOException
        Creates a new ZIP entry taking some information from the given path and using the provided name.

        The name will be adjusted to end with a forward slash "/" if the file is a directory. If the file is not a directory a potential trailing forward slash will be stripped from the entry name.

        Parameters:
        extraFieldFactory - custom lookup factory for extra fields or null
        inputPath - path to create the entry from.
        entryName - name of the entry.
        options - options indicating how symbolic links are handled.
        Throws:
        java.io.IOException - if an I/O error occurs.

      • ZipArchiveEntry

        private ZipArchiveEntry​(java.util.function.Function<ZipShort,​ZipExtraField> extraFieldFactory,
                        java.lang.String name)
        Creates a new ZIP entry with the specified name.

        Assumes the entry represents a directory if and only if the name ends with a forward slash "/".

        Parameters:
        extraFieldFactory - custom lookup factory for extra fields or null
        name - the name of the entry

      • ZipArchiveEntry

        private ZipArchiveEntry​(java.util.function.Function<ZipShort,​ZipExtraField> extraFieldFactory,
                        java.util.zip.ZipEntry entry)
                 throws java.util.zip.ZipException
        Creates a new ZIP entry with fields taken from the specified ZIP entry.

        Assumes the entry represents a directory if and only if the name ends with a forward slash "/".

        Parameters:
        extraFieldFactory - the extra field lookup factory.
        entry - the entry to get fields from
        Throws:
        java.util.zip.ZipException - on error

      • ZipArchiveEntry

        public ZipArchiveEntry​(java.nio.file.Path inputPath,
                       java.lang.String entryName,
                       java.nio.file.LinkOption... options)
                throws java.io.IOException
        Creates a new ZIP entry taking some information from the given path and using the provided name.

        The name will be adjusted to end with a forward slash "/" if the file is a directory. If the file is not a directory a potential trailing forward slash will be stripped from the entry name.

        Parameters:
        inputPath - path to create the entry from.
        entryName - name of the entry.
        options - options indicating how symbolic links are handled.
        Throws:
        java.io.IOException - if an I/O error occurs.
        Since:
        1.21

      • ZipArchiveEntry

        public ZipArchiveEntry​(java.lang.String name)
        Creates a new ZIP entry with the specified name.

        Assumes the entry represents a directory if and only if the name ends with a forward slash "/".

        Parameters:
        name - the name of the entry
        Since:
        1.26.0

      • ZipArchiveEntry

        public ZipArchiveEntry​(ZipArchiveEntry entry)
                throws java.util.zip.ZipException
        Creates a new ZIP entry with fields taken from the specified ZIP entry.

        Assumes the entry represents a directory if and only if the name ends with a forward slash "/".

        Parameters:
        entry - the entry to get fields from
        Throws:
        java.util.zip.ZipException - on error

      • ZipArchiveEntry

        public ZipArchiveEntry​(java.util.zip.ZipEntry entry)
                throws java.util.zip.ZipException
        Creates a new ZIP entry with fields taken from the specified ZIP entry.

        Assumes the entry represents a directory if and only if the name ends with a forward slash "/".

        Parameters:
        entry - the entry to get fields from
        Throws:
        java.util.zip.ZipException - on error

    • Method Detail

      • canConvertToInfoZipExtendedTimestamp

        private static boolean canConvertToInfoZipExtendedTimestamp​(java.nio.file.attribute.FileTime lastModifiedTime,
                                                            java.nio.file.attribute.FileTime lastAccessTime,
                                                            java.nio.file.attribute.FileTime creationTime)

      • isDirectoryEntryName

        private static boolean isDirectoryEntryName​(java.lang.String entryName)

      • toDirectoryEntryName

        private static java.lang.String toDirectoryEntryName​(java.lang.String entryName)

      • toEntryName

        private static java.lang.String toEntryName​(java.io.File inputFile,
                                            java.lang.String entryName)

      • toEntryName

        private static java.lang.String toEntryName​(java.nio.file.Path inputPath,
                                            java.lang.String entryName,
                                            java.nio.file.LinkOption... options)

      • addAsFirstExtraField

        public void addAsFirstExtraField​(ZipExtraField ze)
        Adds an extra field - replacing an already present extra field of the same type.

        The new extra field will be the first one.

        Parameters:
        ze - an extra field

      • addExtraField

        public void addExtraField​(ZipExtraField ze)
        Adds an extra field - replacing an already present extra field of the same type.

        If no extra field of the same type exists, the field will be added as last field.

        Parameters:
        ze - an extra field

      • addInfoZipExtendedTimestamp

        private void addInfoZipExtendedTimestamp​(java.nio.file.attribute.FileTime lastModifiedTime,
                                         java.nio.file.attribute.FileTime lastAccessTime,
                                         java.nio.file.attribute.FileTime creationTime)

      • addNTFSTimestamp

        private void addNTFSTimestamp​(java.nio.file.attribute.FileTime lastModifiedTime,
                              java.nio.file.attribute.FileTime lastAccessTime,
                              java.nio.file.attribute.FileTime creationTime)

      • clone

        public java.lang.Object clone()
        Overwrite clone.
        Overrides:
        clone in class java.util.zip.ZipEntry
        Returns:
        a cloned copy of this ZipArchiveEntry

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • getAlignment

        protected int getAlignment()
        Gets currently configured alignment.
        Returns:
        alignment for this entry.
        Since:
        1.14

      • getAllExtraFields

        private ZipExtraField[] getAllExtraFields()

      • getAllExtraFieldsNoCopy

        private ZipExtraField[] getAllExtraFieldsNoCopy()
        Gets all extra fields, including unparseable ones.
        Returns:
        An array of all extra fields. Not necessarily a copy of internal data structures, hence private method

      • getCentralDirectoryExtra

        public byte[] getCentralDirectoryExtra()
        Retrieves the extra data for the central directory.
        Returns:
        the central directory extra data

      • getCommentSource

        public ZipArchiveEntry.CommentSource getCommentSource()
        The source of the comment field value.
        Returns:
        source of the comment field value
        Since:
        1.16

      • getDataOffset

        public long getDataOffset()
        Description copied from interface: EntryStreamOffsets
        Gets the offset of data stream within the archive file,
        Specified by:
        getDataOffset in interface EntryStreamOffsets
        Returns:
        the offset of entry data stream, OFFSET_UNKNOWN if not known.

      • getDiskNumberStart

        public long getDiskNumberStart()
        The number of the split segment this entry starts at.
        Returns:
        the number of the split segment this entry starts at.
        Since:
        1.20

      • getExternalAttributes

        public long getExternalAttributes()
        Retrieves the external file attributes.

        Note: ZipArchiveInputStream is unable to fill this field, you must use ZipFile if you want to read entries using this attribute.

        Returns:
        the external file attributes

      • getExtraField

        public ZipExtraField getExtraField​(ZipShort type)
        Gets an extra field by its header id.
        Parameters:
        type - the header id
        Returns:
        null if no such field exists.

      • getExtraFields

        public ZipExtraField[] getExtraFields()
        Gets all extra fields that have been parsed successfully.

        Note: The set of extra fields may be incomplete when ZipArchiveInputStream has been used as some extra fields use the central directory to store additional information.

        Returns:
        an array of the extra fields

      • getExtraFields

        public ZipExtraField[] getExtraFields​(boolean includeUnparseable)
        Gets extra fields.
        Parameters:
        includeUnparseable - whether to also return unparseable extra fields as UnparseableExtraFieldData if such data exists.
        Returns:
        an array of the extra fields
        Since:
        1.1

      • getGeneralPurposeBit

        public GeneralPurposeBit getGeneralPurposeBit()
        The "general purpose bit" field.
        Returns:
        the general purpose bit
        Since:
        1.1

      • getInternalAttributes

        public int getInternalAttributes()
        Gets the internal file attributes.

        Note: ZipArchiveInputStream is unable to fill this field, you must use ZipFile if you want to read entries using this attribute.

        Returns:
        the internal file attributes

      • getLastModifiedDate

        public java.util.Date getLastModifiedDate()
        Wraps ZipEntry.getTime() with a Date as the entry's last modified date.

        Changes to the implementation of ZipEntry.getTime() leak through and the returned value may depend on your local time zone as well as your version of Java.

        Specified by:
        getLastModifiedDate in interface ArchiveEntry
        Returns:
        the last modified date of this entry.

      • getLocalFileDataExtra

        public byte[] getLocalFileDataExtra()
        Gets the extra data for the local file data.
        Returns:
        the extra data for local file

      • getLocalHeaderOffset

        public long getLocalHeaderOffset()
        Gets the local header offset.
        Returns:
        the local header offset.
        Since:
        1.24.0

      • getMethod

        public int getMethod()
        Gets the compression method of this entry, or -1 if the compression method has not been specified.
        Overrides:
        getMethod in class java.util.zip.ZipEntry
        Returns:
        compression method
        Since:
        1.1

      • getName

        public java.lang.String getName()
        Gets the name of the entry.

        This method returns the raw name as it is stored inside of the archive.

        Specified by:
        getName in interface ArchiveEntry
        Overrides:
        getName in class java.util.zip.ZipEntry
        Returns:
        the entry name

      • getNameSource

        public ZipArchiveEntry.NameSource getNameSource()
        The source of the name field value.
        Returns:
        source of the name field value
        Since:
        1.16

      • getParseableExtraFields

        private ZipExtraField[] getParseableExtraFields()

      • getParseableExtraFieldsNoCopy

        private ZipExtraField[] getParseableExtraFieldsNoCopy()

      • getPlatform

        public int getPlatform()
        Platform specification to put into the "version made by" part of the central file header.
        Returns:
        PLATFORM_FAT unless setUnixMode has been called, in which case PLATFORM_UNIX will be returned.

      • getRawFlag

        public int getRawFlag()
        The content of the flags field.
        Returns:
        content of the flags field
        Since:
        1.11

      • getRawName

        public byte[] getRawName()
        Returns the raw bytes that made up the name before it has been converted using the configured or guessed encoding.

        This method will return null if this instance has not been read from an archive.

        Returns:
        the raw name bytes
        Since:
        1.2

      • getSize

        public long getSize()
        Gets the uncompressed size of the entry data.

        Note: ZipArchiveInputStream may create entries that return SIZE_UNKNOWN as long as the entry hasn't been read completely.

        Specified by:
        getSize in interface ArchiveEntry
        Overrides:
        getSize in class java.util.zip.ZipEntry
        Returns:
        the entry size

      • getTime

        public long getTime()

        Override to work around bug JDK-8130914

        Overrides:
        getTime in class java.util.zip.ZipEntry
        Returns:
        The last modification time of the entry in milliseconds since the epoch, or -1 if not specified
        See Also:
        setTime(long), setLastModifiedTime(FileTime)

      • getUnixMode

        public int getUnixMode()
        Gets the UNIX permission.
        Returns:
        the unix permissions

      • getUnparseableExtraFieldData

        public UnparseableExtraFieldData getUnparseableExtraFieldData()
        Gets up extra field data that couldn't be parsed correctly.
        Returns:
        null if no such field exists.
        Since:
        1.1

      • getUnparseableOnly

        private ZipExtraField[] getUnparseableOnly()

      • getVersionMadeBy

        public int getVersionMadeBy()
        Gets the "version made by" field.
        Returns:
        "version made by" field
        Since:
        1.11

      • getVersionRequired

        public int getVersionRequired()
        Gets the "version required to expand" field.
        Returns:
        "version required to expand" field
        Since:
        1.11

      • hashCode

        public int hashCode()
        Gets the hash code of the entry. This uses the name as the hash code.
        Overrides:
        hashCode in class java.util.zip.ZipEntry
        Returns:
        a hash code.

      • internalAddExtraField

        private void internalAddExtraField​(ZipExtraField ze)

      • internalRemoveExtraField

        private void internalRemoveExtraField​(ZipShort type)

      • internalSetLastModifiedTime

        private void internalSetLastModifiedTime​(java.nio.file.attribute.FileTime time)

      • isDirectory

        public boolean isDirectory()
        Is this entry a directory?
        Specified by:
        isDirectory in interface ArchiveEntry
        Overrides:
        isDirectory in class java.util.zip.ZipEntry
        Returns:
        true if the entry is a directory

      • isStreamContiguous

        public boolean isStreamContiguous()
        Description copied from interface: EntryStreamOffsets
        Tests whether the stream is contiguous, that is, not split among several archive parts, interspersed with control blocks, and so on.
        Specified by:
        isStreamContiguous in interface EntryStreamOffsets
        Returns:
        true if stream is contiguous, false otherwise.

      • isUnixSymlink

        public boolean isUnixSymlink()
        Returns true if this entry represents a unix symlink, in which case the entry's content contains the target path for the symlink.
        Returns:
        true if the entry represents a unix symlink, false otherwise.
        Since:
        1.5

      • mergeExtraFields

        private void mergeExtraFields​(ZipExtraField[] f,
                              boolean local)
        If there are no extra fields, use the given fields as new extra data - otherwise merge the fields assuming the existing fields and the new fields stem from different locations inside the archive.
        Parameters:
        f - the extra fields to merge
        local - whether the new fields originate from local data

      • parseExtraFields

        private ZipExtraField[] parseExtraFields​(byte[] data,
                                         boolean local,
                                         ExtraFieldParsingBehavior parsingBehavior)
                                  throws java.util.zip.ZipException
        Throws:
        java.util.zip.ZipException

      • removeExtraField

        public void removeExtraField​(ZipShort type)
        Remove an extra field.
        Parameters:
        type - the type of extra field to remove

      • removeUnparseableExtraFieldData

        public void removeUnparseableExtraFieldData()
        Removes unparseable extra field data.
        Since:
        1.1

      • requiresExtraTimeFields

        private boolean requiresExtraTimeFields()

      • setAlignment

        public void setAlignment​(int alignment)
        Sets alignment for this entry.
        Parameters:
        alignment - requested alignment, 0 for default.
        Since:
        1.14

      • setAttributes

        private void setAttributes​(java.nio.file.Path inputPath,
                           java.nio.file.LinkOption... options)
                    throws java.io.IOException
        Throws:
        java.io.IOException

      • setCentralDirectoryExtra

        public void setCentralDirectoryExtra​(byte[] b)
        Sets the central directory part of extra fields.
        Parameters:
        b - an array of bytes to be parsed into extra fields

      • setCommentSource

        public void setCommentSource​(ZipArchiveEntry.CommentSource commentSource)
        Sets the source of the comment field value.
        Parameters:
        commentSource - source of the comment field value
        Since:
        1.16

      • setCreationTime

        public java.util.zip.ZipEntry setCreationTime​(java.nio.file.attribute.FileTime time)
        Overrides:
        setCreationTime in class java.util.zip.ZipEntry

      • setDataOffset

        protected void setDataOffset​(long dataOffset)
        Sets the data offset.
        Parameters:
        dataOffset - new value of data offset.

      • setDiskNumberStart

        public void setDiskNumberStart​(long diskNumberStart)
        The number of the split segment this entry starts at.
        Parameters:
        diskNumberStart - the number of the split segment this entry starts at.
        Since:
        1.20

      • setExternalAttributes

        public void setExternalAttributes​(long value)
        Sets the external file attributes.
        Parameters:
        value - an long value

      • setExtra

        protected void setExtra()
        Unfortunately ZipOutputStream seems to access the extra data directly, so overriding getExtra doesn't help - we need to modify super's data directly and on every update.

      • setExtra

        public void setExtra​(byte[] extra)
              throws java.lang.RuntimeException
        Parses the given bytes as extra field data and consumes any unparseable data as an UnparseableExtraFieldData instance.
        Overrides:
        setExtra in class java.util.zip.ZipEntry
        Parameters:
        extra - an array of bytes to be parsed into extra fields
        Throws:
        java.lang.RuntimeException - if the bytes cannot be parsed
        java.lang.RuntimeException - on error

      • setExtraFields

        public void setExtraFields​(ZipExtraField[] fields)
        Replaces all currently attached extra fields with the new array.
        Parameters:
        fields - an array of extra fields

      • setExtraTimeFields

        private void setExtraTimeFields()

      • setGeneralPurposeBit

        public void setGeneralPurposeBit​(GeneralPurposeBit generalPurposeBit)
        Sets the "general purpose bit" field.
        Parameters:
        generalPurposeBit - the general purpose bit
        Since:
        1.1

      • setInternalAttributes

        public void setInternalAttributes​(int internalAttributes)
        Sets the internal file attributes.
        Parameters:
        internalAttributes - an int value

      • setLastAccessTime

        public java.util.zip.ZipEntry setLastAccessTime​(java.nio.file.attribute.FileTime fileTime)
        Overrides:
        setLastAccessTime in class java.util.zip.ZipEntry

      • setLastModifiedTime

        public java.util.zip.ZipEntry setLastModifiedTime​(java.nio.file.attribute.FileTime fileTime)
        Overrides:
        setLastModifiedTime in class java.util.zip.ZipEntry

      • setLocalHeaderOffset

        protected void setLocalHeaderOffset​(long localHeaderOffset)

      • setMethod

        public void setMethod​(int method)
        Sets the compression method of this entry.
        Overrides:
        setMethod in class java.util.zip.ZipEntry
        Parameters:
        method - compression method
        Since:
        1.1

      • setName

        protected void setName​(java.lang.String name)
        Sets the name of the entry.
        Parameters:
        name - the name to use

      • setName

        protected void setName​(java.lang.String name,
                       byte[] rawName)
        Sets the name using the raw bytes and the string created from it by guessing or using the configured encoding.
        Parameters:
        name - the name to use created from the raw bytes using the guessed or configured encoding
        rawName - the bytes originally read as name from the archive
        Since:
        1.2

      • setNameSource

        public void setNameSource​(ZipArchiveEntry.NameSource nameSource)
        Sets the source of the name field value.
        Parameters:
        nameSource - source of the name field value
        Since:
        1.16

      • setPlatform

        protected void setPlatform​(int platform)
        Sets the platform (UNIX or FAT).
        Parameters:
        platform - an int value - 0 is FAT, 3 is UNIX

      • setRawFlag

        public void setRawFlag​(int rawFlag)
        Sets the content of the flags field.
        Parameters:
        rawFlag - content of the flags field
        Since:
        1.11

      • setSize

        public void setSize​(long size)
        Sets the uncompressed size of the entry data.
        Overrides:
        setSize in class java.util.zip.ZipEntry
        Parameters:
        size - the uncompressed size in bytes
        Throws:
        java.lang.IllegalArgumentException - if the specified size is less than 0

      • setStreamContiguous

        protected void setStreamContiguous​(boolean isStreamContiguous)

      • setTime

        public void setTime​(java.nio.file.attribute.FileTime fileTime)
        Sets the modification time of the entry.
        Parameters:
        fileTime - the entry modification time.
        Since:
        1.21

      • setTime

        public void setTime​(long timeEpochMillis)

        Override to work around bug JDK-8130914

        Overrides:
        setTime in class java.util.zip.ZipEntry
        Parameters:
        timeEpochMillis - The last modification time of the entry in milliseconds since the epoch.
        See Also:
        getTime(), ZipEntry.getLastModifiedTime()

      • setUnixMode

        public void setUnixMode​(int mode)
        Sets UNIX permissions in a way that is understood by Info-Zip's unzip command.
        Parameters:
        mode - an int value

      • setVersionMadeBy

        public void setVersionMadeBy​(int versionMadeBy)
        Sets the "version made by" field.
        Parameters:
        versionMadeBy - "version made by" field
        Since:
        1.11

      • setVersionRequired

        public void setVersionRequired​(int versionRequired)
        Sets the "version required to expand" field.
        Parameters:
        versionRequired - "version required to expand" field
        Since:
        1.11

      • updateTimeFieldsFromExtraFields

        private void updateTimeFieldsFromExtraFields()

      • updateTimeFromExtendedTimestampField

        private void updateTimeFromExtendedTimestampField()
        Workaround for the fact that, as of Java 17, ZipEntry does not properly modify the entry's xdostime field, only setting mtime. While this is not strictly necessary, it's better to maintain the same behavior between this and the NTFS field.

      • updateTimeFromNtfsField

        private void updateTimeFromNtfsField()
        Workaround for the fact that, as of Java 17, ZipEntry parses NTFS timestamps with a maximum precision of microseconds, which is lower than the 100ns precision provided by this extra field.