DumpArchiveEntry
Date: 2017-02-08

org.apache.commons.compress.archivers.dump

## Class DumpArchiveEntry

- java.lang.Object
- - org.apache.commons.compress.archivers.dump.DumpArchiveEntry

- All Implemented Interfaces:
    ArchiveEntry

      public class DumpArchiveEntry
      extends java.lang.Object
      implements ArchiveEntry

  This class represents an entry in a Dump archive. It consists of the entry's header, the entry's File and any extended attributes.

  DumpEntries that are created from the header bytes read from an archive are instantiated with the DumpArchiveEntry( byte[] ) constructor. These entries will be used when extracting from or listing the contents of an archive. These entries have their header filled in using the header bytes. They also set the File to null, since they reference an archive entry not a file.

  DumpEntries can also be constructed from nothing but a name. This allows the programmer to construct the entry by hand, for instance when only an InputStream is available for writing to the archive, and the header information is constructed from other information. In this case the header fields are set to defaults and the File is set to null.

  The C structure for a Dump Entry's header is:

       #define TP_BSIZE    1024          // size of each file block
       #define NTREC       10            // number of blocks to write at once
       #define HIGHDENSITYTREC 32        // number of blocks to write on high-density tapes
       #define TP_NINDIR   (TP_BSIZE/2)  // number if indirect inodes in record
       #define TP_NINOS    (TP_NINDIR / sizeof (int32_t))
       #define LBLSIZE     16
       #define NAMELEN     64

       #define OFS_MAGIC     (int)60011  // old format magic value
       #define NFS_MAGIC     (int)60012  // new format magic value
       #define FS_UFS2_MAGIC (int)0x19540119
       #define CHECKSUM      (int)84446  // constant used in checksum algorithm

       struct  s_spcl {
         int32_t c_type;             // record type (see below)
         int32_t c_date;             // date of this dump
         int32_t c_ddate;            // date of previous dump
         int32_t c_volume;           // dump volume number
         u_int32_t c_tapea;          // logical block of this record
         dump_ino_t c_ino;           // number of inode
         int32_t c_magic;            // magic number (see above)
         int32_t c_checksum;         // record checksum
       #ifdef  __linux__
         struct  new_bsd_inode c_dinode;
       #else
       #ifdef sunos
         struct  new_bsd_inode c_dinode;
       #else
         struct  dinode  c_dinode;   // ownership and mode of inode
       #endif
       #endif
         int32_t c_count;            // number of valid c_addr entries
         union u_data c_data;        // see above
         char    c_label[LBLSIZE];   // dump label
         int32_t c_level;            // level of this dump
         char    c_filesys[NAMELEN]; // name of dumpped file system
         char    c_dev[NAMELEN];     // name of dumpped device
         char    c_host[NAMELEN];    // name of dumpped host
         int32_t c_flags;            // additional information (see below)
         int32_t c_firstrec;         // first record on volume
         int32_t c_ntrec;            // blocksize on volume
         int32_t c_extattributes;    // additional inode info (see below)
         int32_t c_spare[30];        // reserved for future uses
       } s_spcl;

       //
       // flag values
       //
       #define DR_NEWHEADER     0x0001  // new format tape header
       #define DR_NEWINODEFMT   0x0002  // new format inodes on tape
       #define DR_COMPRESSED    0x0080  // dump tape is compressed
       #define DR_METAONLY      0x0100  // only the metadata of the inode has been dumped
       #define DR_INODEINFO     0x0002  // [SIC] TS_END header contains c_inos information
       #define DR_EXTATTRIBUTES 0x8000

       //
       // extattributes inode info
       //
       #define EXT_REGULAR         0
       #define EXT_MACOSFNDRINFO   1
       #define EXT_MACOSRESFORK    2
       #define EXT_XATTR           3

       // used for EA on tape
       #define EXT2_GOOD_OLD_INODE_SIZE    128
       #define EXT2_XATTR_MAGIC        0xEA020000  // block EA
       #define EXT2_XATTR_MAGIC2       0xEA020001  // in inode EA

  The fields in bold are the same for all blocks. (This permitted multiple dumps to be written to a single tape.)

  The C structure for the inode (file) information is:

       struct bsdtimeval {           //  **** alpha-*-linux is deviant
         __u32   tv_sec;
         __u32   tv_usec;
       };

       #define NDADDR      12
       #define NIADDR       3

       //
       // This is the new (4.4) BSD inode structure
       // copied from the FreeBSD 2.0 <ufs/ufs/dinode.h> include file
       //
       struct new_bsd_inode {
         __u16       di_mode;           // file type, standard Unix permissions
         __s16       di_nlink;          // number of hard links to file.
         union {
            __u16       oldids[2];
            __u32       inumber;
         }           di_u;
         u_quad_t    di_size;           // file size
         struct bsdtimeval   di_atime;  // time file was last accessed
         struct bsdtimeval   di_mtime;  // time file was last modified
         struct bsdtimeval   di_ctime;  // time file was created
         __u32       di_db[NDADDR];
         __u32       di_ib[NIADDR];
         __u32       di_flags;          //
         __s32       di_blocks;         // number of disk blocks
         __s32       di_gen;            // generation number
         __u32       di_uid;            // user id (see /etc/passwd)
         __u32       di_gid;            // group id (see /etc/group)
         __s32       di_spare[2];       // unused
       };

  It is important to note that the header DOES NOT have the name of the file. It can't since hard links mean that you may have multiple filenames for a single physical file. You must read the contents of the directory entries to learn the mapping(s) from filename to inode.

  The C structure that indicates if a specific block is a real block that contains data or is a sparse block that is not persisted to the disk is:

       #define TP_BSIZE    1024
       #define TP_NINDIR   (TP_BSIZE/2)

       union u_data {
         char    s_addrs[TP_NINDIR]; // 1 => data; 0 => hole in inode
         int32_t s_inos[TP_NINOS];   // table of first inode on each volume
       } u_data;

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DumpArchiveEntry.PERMISSION`
    `static class` | `DumpArchiveEntry.TYPE`

  - ### Field Summary

    - ### Fields inherited from interface org.apache.commons.compress.archivers.ArchiveEntry

      `SIZE_UNKNOWN`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `DumpArchiveEntry()` Default constructor.
    `` | `DumpArchiveEntry(java.lang.String name, java.lang.String simpleName)` Constructor taking only filename.
    `protected` | `DumpArchiveEntry(java.lang.String name, java.lang.String simpleName, int ino, DumpArchiveEntry.TYPE type)` Constructor taking name, inode and type.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object o)`
    `java.util.Date` | `getAccessTime()` Returns the time the file was last accessed.
    `java.util.Date` | `getCreationTime()` Get file creation time.
    `int` | `getGeneration()` Return the generation of the file.
    `int` | `getGroupId()` Return the group id
    `int` | `getHeaderCount()` Return the number of records in this segment.
    `int` | `getHeaderHoles()` Return the number of sparse records in this segment.
    `DumpArchiveConstants.SEGMENT_TYPE` | `getHeaderType()` Return the type of the tape segment header.
    `int` | `getIno()` Returns the ino of the entry.
    `java.util.Date` | `getLastModifiedDate()` The last modified date.
    `int` | `getMode()` Return the access permissions on the entry.
    `java.lang.String` | `getName()` Returns the name of the entry.
    `int` | `getNlink()` Return the number of hard links to the entry.
    `long` | `getOffset()` Return the offset within the archive
    `java.util.Set<DumpArchiveEntry.PERMISSION>` | `getPermissions()` Returns the permissions on the entry.
    `java.lang.String` | `getSimpleName()` Returns the path of the entry.
    `long` | `getSize()` Returns the size of the entry.
    `DumpArchiveEntry.TYPE` | `getType()` Get the type of the entry.
    `int` | `getUserId()` Return the user id.
    `int` | `getVolume()` Return the tape volume where this file is located.
    `int` | `hashCode()`
    `boolean` | `isBlkDev()` Is this a block device?
    `boolean` | `isChrDev()` Is this a character device?
    `boolean` | `isDeleted()` Has this file been deleted? (On valid on incremental dumps.)
    `boolean` | `isDirectory()` Is this a directory?
    `boolean` | `isFifo()` Is this a fifo/pipe?
    `boolean` | `isFile()` Is this a regular file?
    `boolean` | `isSocket()` Is this a network device?
    `boolean` | `isSparseRecord(int idx)` Is this a sparse record?
    `void` | `setAccessTime(java.util.Date atime)` Set the time the file was last accessed.
    `void` | `setCreationTime(java.util.Date ctime)` Set the file creation time.
    `void` | `setDeleted(boolean isDeleted)` Set whether this file has been deleted.
    `void` | `setGeneration(int generation)` Set the generation of the file.
    `void` | `setGroupId(int gid)` Set the group id.
    `void` | `setLastModifiedDate(java.util.Date mtime)` Set the time the file was last modified.
    `void` | `setMode(int mode)` Set the access permissions on the entry.
    `void` | `setName(java.lang.String name)` Sets the name of the entry.
    `void` | `setNlink(int nlink)` Set the number of hard links.
    `void` | `setOffset(long offset)` Set the offset within the archive.
    `protected void` | `setSimpleName(java.lang.String simpleName)` Sets the path of the entry.
    `void` | `setSize(long size)` Set the size of the entry.
    `void` | `setType(DumpArchiveEntry.TYPE type)` Set the type of the entry.
    `void` | `setUserId(int uid)` Set the user id.
    `void` | `setVolume(int volume)` Set the tape volume.
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### DumpArchiveEntry

          public DumpArchiveEntry()

      Default constructor.

    - #### DumpArchiveEntry

          public DumpArchiveEntry(java.lang.String name,
                          java.lang.String simpleName)

      Constructor taking only filename.
      Parameters:
        `name` - pathname
        `simpleName` - actual filename.

    - #### DumpArchiveEntry

          protected DumpArchiveEntry(java.lang.String name,
                          java.lang.String simpleName,
                          int ino,
                          DumpArchiveEntry.TYPE type)

      Constructor taking name, inode and type.
      Parameters:
        `name` - the name
        `simpleName` - the simple name
        `ino` - the ino
        `type` - the type

  - ### Method Detail

    - #### getSimpleName

          public java.lang.String getSimpleName()

      Returns the path of the entry.
      Returns:
        the path of the entry.

    - #### setSimpleName

          protected void setSimpleName(java.lang.String simpleName)

      Sets the path of the entry.
      Parameters:
        `simpleName` - the simple name

    - #### getIno

          public int getIno()

      Returns the ino of the entry.
      Returns:
        the ino

    - #### getNlink

          public int getNlink()

      Return the number of hard links to the entry.
      Returns:
        the number of hard links

    - #### setNlink

          public void setNlink(int nlink)

      Set the number of hard links.
      Parameters:
        `nlink` - the number of hard links

    - #### getCreationTime

          public java.util.Date getCreationTime()

      Get file creation time.
      Returns:
        the creation time

    - #### setCreationTime

          public void setCreationTime(java.util.Date ctime)

      Set the file creation time.
      Parameters:
        `ctime` - the creation time

    - #### getGeneration

          public int getGeneration()

      Return the generation of the file.
      Returns:
        the generation

    - #### setGeneration

          public void setGeneration(int generation)

      Set the generation of the file.
      Parameters:
        `generation` - the generation

    - #### isDeleted

          public boolean isDeleted()

      Has this file been deleted? (On valid on incremental dumps.)
      Returns:
        whether the file has been deleted

    - #### setDeleted

          public void setDeleted(boolean isDeleted)

      Set whether this file has been deleted.
      Parameters:
        `isDeleted` - whether the file has been deleted

    - #### getOffset

          public long getOffset()

      Return the offset within the archive
      Returns:
        the offset

    - #### setOffset

          public void setOffset(long offset)

      Set the offset within the archive.
      Parameters:
        `offset` - the offset

    - #### getVolume

          public int getVolume()

      Return the tape volume where this file is located.
      Returns:
        the volume

    - #### setVolume

          public void setVolume(int volume)

      Set the tape volume.
      Parameters:
        `volume` - the volume

    - #### getHeaderType

          public DumpArchiveConstants.SEGMENT_TYPE getHeaderType()

      Return the type of the tape segment header.
      Returns:
        the segment header

    - #### getHeaderCount

          public int getHeaderCount()

      Return the number of records in this segment.
      Returns:
        the number of records

    - #### getHeaderHoles

          public int getHeaderHoles()

      Return the number of sparse records in this segment.
      Returns:
        the number of sparse records

    - #### isSparseRecord

          public boolean isSparseRecord(int idx)

      Is this a sparse record?
      Parameters:
        `idx` - index of the record to check
      Returns:
        whether this is a sparse record

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getName

          public java.lang.String getName()

      Returns the name of the entry.
      Specified by:
        `getName` in interface `ArchiveEntry`
      Returns:
        the name of the entry.

    - #### setName

          public final void setName(java.lang.String name)

      Sets the name of the entry.
      Parameters:
        `name` - the name

    - #### getLastModifiedDate

          public java.util.Date getLastModifiedDate()

      The last modified date.
      Specified by:
        `getLastModifiedDate` in interface `ArchiveEntry`
      Returns:
        the last modified date

    - #### isDirectory

          public boolean isDirectory()

      Is this a directory?
      Specified by:
        `isDirectory` in interface `ArchiveEntry`
      Returns:
        whether this is a directory

    - #### isFile

          public boolean isFile()

      Is this a regular file?
      Returns:
        whether this is a regular file

    - #### isSocket

          public boolean isSocket()

      Is this a network device?
      Returns:
        whether this is a socket

    - #### isChrDev

          public boolean isChrDev()

      Is this a character device?
      Returns:
        whether this is a character device

    - #### isBlkDev

          public boolean isBlkDev()

      Is this a block device?
      Returns:
        whether this is a block device

    - #### isFifo

          public boolean isFifo()

      Is this a fifo/pipe?
      Returns:
        whether this is a fifo

    - #### getType

          public DumpArchiveEntry.TYPE getType()

      Get the type of the entry.
      Returns:
        the type

    - #### setType

          public void setType(DumpArchiveEntry.TYPE type)

      Set the type of the entry.
      Parameters:
        `type` - the type

    - #### getMode

          public int getMode()

      Return the access permissions on the entry.
      Returns:
        the access permissions

    - #### setMode

          public void setMode(int mode)

      Set the access permissions on the entry.
      Parameters:
        `mode` - the access permissions

    - #### getPermissions

          public java.util.Set<DumpArchiveEntry.PERMISSION> getPermissions()

      Returns the permissions on the entry.
      Returns:
        the permissions

    - #### getSize

          public long getSize()

      Returns the size of the entry.
      Specified by:
        `getSize` in interface `ArchiveEntry`
      Returns:
        the size

    - #### setSize

          public void setSize(long size)

      Set the size of the entry.
      Parameters:
        `size` - the size

    - #### setLastModifiedDate

          public void setLastModifiedDate(java.util.Date mtime)

      Set the time the file was last modified.
      Parameters:
        `mtime` - the last modified time

    - #### getAccessTime

          public java.util.Date getAccessTime()

      Returns the time the file was last accessed.
      Returns:
        the access time

    - #### setAccessTime

          public void setAccessTime(java.util.Date atime)

      Set the time the file was last accessed.
      Parameters:
        `atime` - the access time

    - #### getUserId

          public int getUserId()

      Return the user id.
      Returns:
        the user id

    - #### setUserId

          public void setUserId(int uid)

      Set the user id.
      Parameters:
        `uid` - the user id

    - #### getGroupId

          public int getGroupId()

      Return the group id
      Returns:
        the group id

    - #### setGroupId

          public void setGroupId(int gid)

      Set the group id.
      Parameters:
        `gid` - the group id