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

Class X5455_ExtendedTimestamp

java.lang.Object
org.apache.commons.compress.archivers.zip.X5455_ExtendedTimestamp
All Implemented Interfaces:
Serializable, Cloneable, ZipExtraField
public class X5455_ExtendedTimestamp extends Object implements ZipExtraField, Cloneable, Serializable

An extra field that stores additional file and directory timestamp data for ZIP entries. Each ZIP entry can include up to three timestamps (modify, access, create*). The timestamps are stored as 32 bit signed integers representing seconds since UNIX epoch (Jan 1st, 1970, UTC). This field improves on ZIP's default timestamp granularity, since it allows one to store additional timestamps, and, in addition, the timestamps are stored using per-second granularity (zip's default behavior can only store timestamps to the nearest even second).

Unfortunately, 32 (signed) bits can only store dates up to the year 2037, and so this extra field will eventually be obsolete. Enjoy it while it lasts!

  • modifyTime: most recent time of file/directory modification (or file/dir creation if the entry has not been modified since it was created).
  • accessTime: most recent time file/directory was opened (e.g., read from disk). Many people disable their operating systems from updating this value using the NOATIME mount option to optimize disk behavior, and thus it's not always reliable. In those cases it's always equal to modifyTime.
  • *createTime: modern Linux file systems (e.g., ext2 and newer) do not appear to store a value like this, and so it's usually omitted altogether in the ZIP extra field. Perhaps other UNIX systems track this.

We're using the field definition given in Info-Zip's source archive: zip-3.0.tar.gz/proginfo/extrafld.txt 

 Value         Size        Description
 -----         ----        -----------
 0x5455        Short       tag for this extra block type ("UT")
 TSize         Short       total data size for this block
 Flags         Byte        info bits
 (ModTime)     Long        time of last modification (UTC/GMT)
 (AcTime)      Long        time of last access (UTC/GMT)
 (CrTime)      Long        time of original creation (UTC/GMT)

 Central-header version:

 Value         Size        Description
 -----         ----        -----------
 0x5455        Short       tag for this extra block type ("UT")
 TSize         Short       total data size for this block
 Flags         Byte        info bits (refers to local header!)
 (ModTime)     Long        time of last modification (UTC/GMT)
Since:
1.5
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final byte
    ACCESS_TIME_BIT
    The bit set inside the flags by when the lasr access time is present in this extra field.
    static final byte
    CREATE_TIME_BIT
    The bit set inside the flags by when the original creation time is present in this extra field.
    static final ZipShort
    HEADER_ID
    The header ID for this extra field.
    static final byte
    MODIFY_TIME_BIT
    The bit set inside the flags by when the last modification time is present in this extra field.

    Fields inherited from interface org.apache.commons.compress.archivers.zip.ZipExtraField

    EXTRAFIELD_HEADER_SIZE

  • Constructor Summary

    Constructors
    Constructor
    Description
    X5455_ExtendedTimestamp()
    Constructor for X5455_ExtendedTimestamp.

  • Method Summary

    Modifier and Type
    Method
    Description
    Object
    clone()
     
    boolean
    equals(Object o)
     
    FileTime
    getAccessFileTime()
    Gets the access time as a FileTime of this ZIP entry, or null if no such timestamp exists in the ZIP entry.
    Date
    getAccessJavaTime()
    Gets the access time as a java.util.Date of this ZIP entry, or null if no such timestamp exists in the ZIP entry.
    ZipLong
    getAccessTime()
    Gets the access time (seconds since epoch) of this ZIP entry as a ZipLong object, or null if no such timestamp exists in the ZIP entry.
    byte[]
    getCentralDirectoryData()
    Gets the actual data to put into central directory data - without Header-ID or length specifier.
    ZipShort
    getCentralDirectoryLength()
    Gets the length of the extra field in the local file data - without Header-ID or length specifier.
    FileTime
    getCreateFileTime()
    Gets the create time as a FileTime of this ZIP entry, or null if no such timestamp exists in the ZIP entry.
    Date
    getCreateJavaTime()
    Gets the create time as a java.util.Date of this ZIP entry, or null if no such timestamp exists in the ZIP entry.
    ZipLong
    getCreateTime()
    Gets the create time (seconds since epoch) of this ZIP entry as a ZipLong object, or null if no such timestamp exists in the ZIP entry.
    byte
    getFlags()
    Gets flags byte.
    ZipShort
    getHeaderId()
    Gets the Header-ID.
    byte[]
    getLocalFileDataData()
    Gets the actual data to put into local file data - without Header-ID or length specifier.
    ZipShort
    getLocalFileDataLength()
    Gets the length of the extra field in the local file data - without Header-ID or length specifier.
    FileTime
    getModifyFileTime()
    Gets the modify time as a FileTime of this ZIP entry, or null if no such timestamp exists in the ZIP entry.
    Date
    getModifyJavaTime()
    Gets the modify time as a java.util.Date of this ZIP entry, or null if no such timestamp exists in the ZIP entry.
    ZipLong
    getModifyTime()
    Gets the modify time (seconds since epoch) of this ZIP entry as a ZipLong object, or null if no such timestamp exists in the ZIP entry.
    int
    hashCode()
     
    boolean
    isBit0_modifyTimePresent()
    Tests whether bit0 of the flags byte is set or not, which should correspond to the presence or absence of a modify timestamp in this particular ZIP entry.
    boolean
    isBit1_accessTimePresent()
    Tests whether bit1 of the flags byte is set or not, which should correspond to the presence or absence of a "last access" timestamp in this particular ZIP entry.
    boolean
    isBit2_createTimePresent()
    Tests whether bit2 of the flags byte is set or not, which should correspond to the presence or absence of a create timestamp in this particular ZIP entry.
    void
    parseFromCentralDirectoryData(byte[] buffer, int offset, int length)
    Doesn't do anything special since this class always uses the same parsing logic for both central directory and local file data.
    void
    parseFromLocalFileData(byte[] data, int offset, int length)
    Populate data from this array as if it was in local file data.
    void
    setAccessFileTime(FileTime time)
    Sets the acccess time as a FileTime of this ZIP entry.
    void
    setAccessJavaTime(Date d)
    Sets the access time as a java.util.Date of this ZIP entry.
    void
    setAccessTime(ZipLong l)
    Sets the access time (seconds since epoch) of this ZIP entry using a ZipLong object
    void
    setCreateFileTime(FileTime time)
    Sets the create time as a FileTime of this ZIP entry.
    void
    setCreateJavaTime(Date d)
    Sets the create time as a java.util.Date of this ZIP entry.
    void
    setCreateTime(ZipLong l)
    Sets the create time (seconds since epoch) of this ZIP entry using a ZipLong object
    void
    setFlags(byte flags)
    Sets flags byte.
    void
    setModifyFileTime(FileTime time)
    Sets the modify time as a FileTime of this ZIP entry.
    void
    setModifyJavaTime(Date d)
    Sets the modify time as a java.util.Date of this ZIP entry.
    void
    setModifyTime(ZipLong l)
    Sets the modify time (seconds since epoch) of this ZIP entry using a ZipLong object.
    String
    toString()
    Returns a String representation of this class useful for debugging purposes.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • HEADER_ID

      public static final ZipShort HEADER_ID
      The header ID for this extra field.
      Since:
      1.23

    • MODIFY_TIME_BIT

      public static final byte MODIFY_TIME_BIT
      The bit set inside the flags by when the last modification time is present in this extra field.
      See Also:

    • ACCESS_TIME_BIT

      public static final byte ACCESS_TIME_BIT
      The bit set inside the flags by when the lasr access time is present in this extra field.
      See Also:

    • CREATE_TIME_BIT

      public static final byte CREATE_TIME_BIT
      The bit set inside the flags by when the original creation time is present in this extra field.
      See Also:

  • Constructor Details

  • Method Details

    • clone

      public Object clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • getAccessFileTime

      public FileTime getAccessFileTime()
      Gets the access time as a FileTime of this ZIP entry, or null if no such timestamp exists in the ZIP entry. The milliseconds are always zeroed out, since the underlying data offers only per-second precision.
      Returns:
      modify time as FileTime or null.
      Since:
      1.23

    • getAccessJavaTime

      public Date getAccessJavaTime()
      Gets the access time as a java.util.Date of this ZIP entry, or null if no such timestamp exists in the ZIP entry. The milliseconds are always zeroed out, since the underlying data offers only per-second precision.
      Returns:
      access time as java.util.Date or null.

    • getAccessTime

      public ZipLong getAccessTime()
      Gets the access time (seconds since epoch) of this ZIP entry as a ZipLong object, or null if no such timestamp exists in the ZIP entry.
      Returns:
      access time (seconds since epoch) or null.

    • getCentralDirectoryData

      public byte[] getCentralDirectoryData()
      Gets the actual data to put into central directory data - without Header-ID or length specifier.
      Specified by:
      getCentralDirectoryData in interface ZipExtraField
      Returns:
      the central directory data

    • getCentralDirectoryLength

      public ZipShort getCentralDirectoryLength()
      Gets the length of the extra field in the local file data - without Header-ID or length specifier.

      For X5455 the central length is often smaller than the local length, because central cannot contain access or create timestamps.

      Specified by:
      getCentralDirectoryLength in interface ZipExtraField
      Returns:
      a ZipShort for the length of the data of this extra field

    • getCreateFileTime

      public FileTime getCreateFileTime()
      Gets the create time as a FileTime of this ZIP entry, or null if no such timestamp exists in the ZIP entry. The milliseconds are always zeroed out, since the underlying data offers only per-second precision.
      Returns:
      modify time as FileTime or null.
      Since:
      1.23

    • getCreateJavaTime

      public Date getCreateJavaTime()

      Gets the create time as a java.util.Date of this ZIP entry, or null if no such timestamp exists in the ZIP entry. The milliseconds are always zeroed out, since the underlying data offers only per-second precision.

      Note: modern Linux file systems (e.g., ext2) do not appear to store a "create time" value, and so it's usually omitted altogether in the ZIP extra field. Perhaps other UNIX systems track this.

      Returns:
      create time as java.util.Date or null.

    • getCreateTime

      public ZipLong getCreateTime()

      Gets the create time (seconds since epoch) of this ZIP entry as a ZipLong object, or null if no such timestamp exists in the ZIP entry.

      Note: modern Linux file systems (e.g., ext2) do not appear to store a "create time" value, and so it's usually omitted altogether in the ZIP extra field. Perhaps other UNIX systems track this.

      Returns:
      create time (seconds since epoch) or null.

    • getFlags

      public byte getFlags()
      Gets flags byte. The flags byte tells us which of the three datestamp fields are present in the data: 
       bit0 - modify time
 bit1 - access time
 bit2 - create time
      Only first 3 bits of flags are used according to the latest version of the spec (December 2012).
      Returns:
      flags byte indicating which of the three datestamp fields are present.

    • getHeaderId

      public ZipShort getHeaderId()
      Gets the Header-ID.
      Specified by:
      getHeaderId in interface ZipExtraField
      Returns:
      the value for the header id for this extrafield

    • getLocalFileDataData

      public byte[] getLocalFileDataData()
      Gets the actual data to put into local file data - without Header-ID or length specifier.
      Specified by:
      getLocalFileDataData in interface ZipExtraField
      Returns:
      get the data

    • getLocalFileDataLength

      public ZipShort getLocalFileDataLength()
      Gets the length of the extra field in the local file data - without Header-ID or length specifier.
      Specified by:
      getLocalFileDataLength in interface ZipExtraField
      Returns:
      a ZipShort for the length of the data of this extra field

    • getModifyFileTime

      public FileTime getModifyFileTime()
      Gets the modify time as a FileTime of this ZIP entry, or null if no such timestamp exists in the ZIP entry. The milliseconds are always zeroed out, since the underlying data offers only per-second precision.
      Returns:
      modify time as FileTime or null.
      Since:
      1.23

    • getModifyJavaTime

      public Date getModifyJavaTime()
      Gets the modify time as a java.util.Date of this ZIP entry, or null if no such timestamp exists in the ZIP entry. The milliseconds are always zeroed out, since the underlying data offers only per-second precision.
      Returns:
      modify time as java.util.Date or null.

    • getModifyTime

      public ZipLong getModifyTime()
      Gets the modify time (seconds since epoch) of this ZIP entry as a ZipLong object, or null if no such timestamp exists in the ZIP entry.
      Returns:
      modify time (seconds since epoch) or null.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • isBit0_modifyTimePresent

      public boolean isBit0_modifyTimePresent()
      Tests whether bit0 of the flags byte is set or not, which should correspond to the presence or absence of a modify timestamp in this particular ZIP entry.
      Returns:
      true if bit0 of the flags byte is set.

    • isBit1_accessTimePresent

      public boolean isBit1_accessTimePresent()
      Tests whether bit1 of the flags byte is set or not, which should correspond to the presence or absence of a "last access" timestamp in this particular ZIP entry.
      Returns:
      true if bit1 of the flags byte is set.

    • isBit2_createTimePresent

      public boolean isBit2_createTimePresent()
      Tests whether bit2 of the flags byte is set or not, which should correspond to the presence or absence of a create timestamp in this particular ZIP entry.
      Returns:
      true if bit2 of the flags byte is set.

    • parseFromCentralDirectoryData

      public void parseFromCentralDirectoryData(byte[] buffer, int offset, int length) throws ZipException
      Doesn't do anything special since this class always uses the same parsing logic for both central directory and local file data.
      Specified by:
      parseFromCentralDirectoryData in interface ZipExtraField
      Parameters:
      buffer - the buffer to read data from
      offset - offset into buffer to read data
      length - the length of data
      Throws:
      ZipException - on error

    • parseFromLocalFileData

      public void parseFromLocalFileData(byte[] data, int offset, int length) throws ZipException
      Populate data from this array as if it was in local file data.
      Specified by:
      parseFromLocalFileData in interface ZipExtraField
      Parameters:
      data - an array of bytes
      offset - the start offset
      length - the number of bytes in the array from offset
      Throws:
      ZipException - on error

    • setAccessFileTime

      public void setAccessFileTime(FileTime time)

      Sets the acccess time as a FileTime of this ZIP entry. Supplied value is truncated to per-second precision (milliseconds zeroed-out).

      Note: the setters for flags and timestamps are decoupled. Even if the timestamp is not-null, it will only be written out if the corresponding bit in the flags is also set.

      Parameters:
      time - access time as FileTime
      Since:
      1.23

    • setAccessJavaTime

      public void setAccessJavaTime(Date d)

      Sets the access time as a java.util.Date of this ZIP entry. Supplied value is truncated to per-second precision (milliseconds zeroed-out).

      Note: the setters for flags and timestamps are decoupled. Even if the timestamp is not-null, it will only be written out if the corresponding bit in the flags is also set.

      Parameters:
      d - access time as java.util.Date

    • setAccessTime

      public void setAccessTime(ZipLong l)

      Sets the access time (seconds since epoch) of this ZIP entry using a ZipLong object

      Note: the setters for flags and timestamps are decoupled. Even if the timestamp is not-null, it will only be written out if the corresponding bit in the flags is also set.

      Parameters:
      l - ZipLong of the access time (seconds per epoch)

    • setCreateFileTime

      public void setCreateFileTime(FileTime time)

      Sets the create time as a FileTime of this ZIP entry. Supplied value is truncated to per-second precision (milliseconds zeroed-out).

      Note: the setters for flags and timestamps are decoupled. Even if the timestamp is not-null, it will only be written out if the corresponding bit in the flags is also set.

      Parameters:
      time - create time as FileTime
      Since:
      1.23

    • setCreateJavaTime

      public void setCreateJavaTime(Date d)

      Sets the create time as a java.util.Date of this ZIP entry. Supplied value is truncated to per-second precision (milliseconds zeroed-out).

      Note: the setters for flags and timestamps are decoupled. Even if the timestamp is not-null, it will only be written out if the corresponding bit in the flags is also set.

      Parameters:
      d - create time as java.util.Date

    • setCreateTime

      public void setCreateTime(ZipLong l)

      Sets the create time (seconds since epoch) of this ZIP entry using a ZipLong object

      Note: the setters for flags and timestamps are decoupled. Even if the timestamp is not-null, it will only be written out if the corresponding bit in the flags is also set.

      Parameters:
      l - ZipLong of the create time (seconds per epoch)

    • setFlags

      public void setFlags(byte flags)
      Sets flags byte. The flags byte tells us which of the three datestamp fields are present in the data: 
       bit0 - modify time
 bit1 - access time
 bit2 - create time
      Only first 3 bits of flags are used according to the latest version of the spec (December 2012).
      Parameters:
      flags - flags byte indicating which of the three datestamp fields are present.

    • setModifyFileTime

      public void setModifyFileTime(FileTime time)

      Sets the modify time as a FileTime of this ZIP entry. Supplied value is truncated to per-second precision (milliseconds zeroed-out).

      Note: the setters for flags and timestamps are decoupled. Even if the timestamp is not-null, it will only be written out if the corresponding bit in the flags is also set.

      Parameters:
      time - modify time as FileTime
      Since:
      1.23

    • setModifyJavaTime

      public void setModifyJavaTime(Date d)

      Sets the modify time as a java.util.Date of this ZIP entry. Supplied value is truncated to per-second precision (milliseconds zeroed-out).

      Note: the setters for flags and timestamps are decoupled. Even if the timestamp is not-null, it will only be written out if the corresponding bit in the flags is also set.

      Parameters:
      d - modify time as java.util.Date

    • setModifyTime

      public void setModifyTime(ZipLong l)

      Sets the modify time (seconds since epoch) of this ZIP entry using a ZipLong object.

      Note: the setters for flags and timestamps are decoupled. Even if the timestamp is not-null, it will only be written out if the corresponding bit in the flags is also set.

      Parameters:
      l - ZipLong of the modify time (seconds per epoch)

    • toString

      public String toString()
      Returns a String representation of this class useful for debugging purposes.
      Overrides:
      toString in class Object
      Returns:
      A String representation of this class useful for debugging purposes.