FsPermission (Apache Hadoop Main 3.5.0 API)
Description: declaration: package: org.apache.hadoop.fs.permission, class: FsPermission

Package org.apache.hadoop.fs.permission

# Class FsPermission

java.lang.Object
org.apache.hadoop.fs.permission.FsPermission

All Implemented Interfaces:
  `ObjectInputValidation`, `Serializable`, `Writable`

Direct Known Subclasses:
  `FsCreateModes`

@Public @Stable public class FsPermission extends Object implements Writable, Serializable, ObjectInputValidation
A class for file/directory permissions.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_UMASK`
  `static final int`
  `MAX_PERMISSION_LENGTH`
  Maximum acceptable length of a permission string to parse
  `static final String`
  `UMASK_LABEL`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FsPermission(int mode)`
  Construct by the given mode.
  `FsPermission(short mode)`
  Construct by the given mode.
  `FsPermission(String mode)`
  Construct by given mode, either in octal or symbolic format.
  `FsPermission(FsAction u, FsAction g, FsAction o)`
  Construct by the given `FsAction`.
  `FsPermission(FsAction u, FsAction g, FsAction o, boolean sb)`
  `FsPermission(FsPermission other)`
  Copy constructor

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FsPermission`
  `applyUMask(FsPermission umask)`
  Apply a umask to this permission and return a new one.
  `static FsPermission`
  `createImmutable(short permission)`
  Create an immutable `FsPermission` object.
  `boolean`
  `equals(Object obj)`
  `void`
  `fromShort(short n)`
  `boolean`
  `getAclBit()`
  Deprecated.
  Get acl bit from the `FileStatus` object.
  `static FsPermission`
  `getCachePoolDefault()`
  Get the default permission for cache pools.
  `static FsPermission`
  `getDefault()`
  Get the default permission for directory and symlink.
  `static FsPermission`
  `getDirDefault()`
  Get the default permission for directory.
  `boolean`
  `getEncryptedBit()`
  Deprecated.
  Get encryption bit from the `FileStatus` object.
  `boolean`
  `getErasureCodedBit()`
  Deprecated.
  Get ec bit from the `FileStatus` object.
  `static FsPermission`
  `getFileDefault()`
  Get the default permission for file.
  `FsAction`
  `getGroupAction()`
  `FsPermission`
  `getMasked()`
  Get masked permission if exists.
  `FsAction`
  `getOtherAction()`
  `boolean`
  `getStickyBit()`
  `static FsPermission`
  `getUMask(Configuration conf)`
  Get the user file creation mask (umask) `UMASK_LABEL` config param has umask value that is either symbolic or octal.
  `FsPermission`
  `getUnmasked()`
  Get unmasked permission if exists.
  `FsAction`
  `getUserAction()`
  `int`
  `hashCode()`
  `static FsPermission`
  `read(DataInput in)`
  Create and initialize a `FsPermission` from `DataInput`.
  `void`
  `readFields(DataInput in)`
  Deprecated.
  `static void`
  `setUMask(Configuration conf, FsPermission umask)`
  Set the user file creation mask (umask)
  `short`
  `toExtendedShort()`
  Deprecated.
  `short`
  `toOctal()`
  Returns the FsPermission in an octal format.
  `short`
  `toShort()`
  Encode the object to a short.
  `String`
  `toString()`
  `void`
  `validateObject()`
  `static FsPermission`
  `valueOf(String unixSymbolicPermission)`
  Create a FsPermission from a Unix symbolic permission string
  `void`
  `write(DataOutput out)`
  Deprecated.

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

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

- ## Field Details

  - ### MAX_PERMISSION_LENGTH

    public static final int MAX_PERMISSION_LENGTH
    Maximum acceptable length of a permission string to parse
    See Also:
      - Constant Field Values

  - ### UMASK_LABEL

    public static final String UMASK_LABEL
    See Also:
      - Constant Field Values

  - ### DEFAULT_UMASK

    public static final int DEFAULT_UMASK
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### FsPermission

    public FsPermission(FsAction u, FsAction g, FsAction o)
    Construct by the given `FsAction`.
    Parameters:
      `u` - user action
      `g` - group action
      `o` - other action

  - ### FsPermission

    public FsPermission(FsAction u, FsAction g, FsAction o, boolean sb)

  - ### FsPermission

    public FsPermission(short mode)
    Construct by the given mode.
    Parameters:
      `mode` - mode.
    See Also:
      - `toShort()`

  - ### FsPermission

    public FsPermission(int mode)
    Construct by the given mode. octal mask is applied.

                      before mask     after mask    file type   sticky bit

            octal     100644            644         file          no
            decimal    33188            420

            octal     101644           1644         file          yes
            decimal    33700           1420

            octal      40644            644         directory     no
            decimal    16804            420

            octal      41644           1644         directory     yes
            decimal    17316           1420

    100644 becomes 644 while 644 remains as 644
    Parameters:
      `mode` - Mode is supposed to come from the result of native stat() call. It contains complete permission information: rwxrwxrwx, sticky bit, whether it is a directory or a file, etc. Upon applying mask, only permission and sticky bit info will be kept because they are the only parts to be used for now.
    See Also:
      - `FsPermission(short mode)`

  - ### FsPermission

    public FsPermission(FsPermission other)
    Copy constructor
    Parameters:
      `other` - other permission

  - ### FsPermission

    public FsPermission(String mode)
    Construct by given mode, either in octal or symbolic format.
    Parameters:
      `mode` - mode as a string, either in octal or symbolic format
    Throws:
      `IllegalArgumentException` - if `mode` is invalid

- ## Method Details

  - ### createImmutable

    public static FsPermission createImmutable(short permission)
    Create an immutable `FsPermission` object.
    Parameters:
      `permission` - permission.
    Returns:
      FsPermission.

  - ### getUserAction

    public FsAction getUserAction()
    Returns:
      Return user `FsAction`.

  - ### getGroupAction

    public FsAction getGroupAction()
    Returns:
      Return group `FsAction`.

  - ### getOtherAction

    public FsAction getOtherAction()
    Returns:
      Return other `FsAction`.

  - ### fromShort

    public void fromShort(short n)

  - ### write

    @Deprecated public void write(DataOutput out) throws IOException
    Deprecated.
    Description copied from interface: `Writable`
    Serialize the fields of this object to `out`.
    Specified by:
      `write` in interface `Writable`
    Parameters:
      `out` - `DataOuput` to serialize this object into.
    Throws:
      `IOException` - any other problem for write.

  - ### readFields

    @Deprecated public void readFields(DataInput in) throws IOException
    Deprecated.
    Description copied from interface: `Writable`
    Deserialize the fields of this object from `in`.

    For efficiency, implementations should attempt to re-use storage in the existing object where possible.

    Specified by:
      `readFields` in interface `Writable`
    Parameters:
      `in` - `DataInput` to deseriablize this object from.
    Throws:
      `IOException` - any other problem for readFields.

  - ### getMasked

    public FsPermission getMasked()
    Get masked permission if exists.
    Returns:
      masked.

  - ### getUnmasked

    public FsPermission getUnmasked()
    Get unmasked permission if exists.
    Returns:
      unmasked.

  - ### read

    public static FsPermission read(DataInput in) throws IOException
    Create and initialize a `FsPermission` from `DataInput`.
    Parameters:
      `in` - data input.
    Returns:
      FsPermission.
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### toShort

    public short toShort()
    Encode the object to a short.
    Returns:
      object to a short.

  - ### toExtendedShort

    @Deprecated public short toExtendedShort()
    Deprecated.
    Encodes the object to a short. Unlike `toShort()`, this method may return values outside the fixed range 00000 - 01777 if extended features are encoded into this permission, such as the ACL bit.
    Returns:
      short extended short representation of this permission

  - ### toOctal

    public short toOctal()
    Returns the FsPermission in an octal format.
    Returns:
      short Unlike `toShort()` which provides a binary representation, this method returns the standard octal style permission.

  - ### equals

    public boolean equals(Object obj)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### applyUMask

    public FsPermission applyUMask(FsPermission umask)
    Apply a umask to this permission and return a new one. The umask is used by create, mkdir, and other Hadoop filesystem operations. The mode argument for these operations is modified by removing the bits which are set in the umask. Thus, the umask limits the permissions which newly created files and directories get.
    Parameters:
      `umask` - The umask to use
    Returns:
      The effective permission

  - ### getUMask

    public static FsPermission getUMask(Configuration conf)
    Get the user file creation mask (umask) `UMASK_LABEL` config param has umask value that is either symbolic or octal. Symbolic umask is applied relative to file mode creation mask; the permission op characters '+' clears the corresponding bit in the mask, '-' sets bits in the mask. Octal umask, the specified bits are set in the file mode creation mask.
    Parameters:
      `conf` - configuration.
    Returns:
      FsPermission UMask.

  - ### getStickyBit

    public boolean getStickyBit()

  - ### getAclBit

    @Deprecated public boolean getAclBit()
    Deprecated.
    Get acl bit from the `FileStatus` object.
    Returns true if there is also an ACL (access control list).
    Returns:
      boolean true if there is also an ACL (access control list).

  - ### getEncryptedBit

    @Deprecated public boolean getEncryptedBit()
    Deprecated.
    Get encryption bit from the `FileStatus` object.
    Returns true if the file is encrypted or directory is in an encryption zone.
    Returns:
      if the file is encrypted or directory is in an encryption zone true, not false.

  - ### getErasureCodedBit

    @Deprecated public boolean getErasureCodedBit()
    Deprecated.
    Get ec bit from the `FileStatus` object.
    Returns true if the file or directory is erasure coded.
    Returns:
      if the file or directory is erasure coded true, not false.

  - ### setUMask

    public static void setUMask(Configuration conf, FsPermission umask)
    Set the user file creation mask (umask)
    Parameters:
      `conf` - configuration.
      `umask` - umask.

  - ### getDefault

    public static FsPermission getDefault()
    Get the default permission for directory and symlink. In previous versions, this default permission was also used to create files, so files created end up with ugo+x permission. See HADOOP-9155 for detail. Two new methods are added to solve this, please use `getDirDefault()` for directory, and use `getFileDefault()` for file. This method is kept for compatibility.
    Returns:
      Default FsPermission.

  - ### getDirDefault

    public static FsPermission getDirDefault()
    Get the default permission for directory.
    Returns:
      DirDefault FsPermission.

  - ### getFileDefault

    public static FsPermission getFileDefault()
    Get the default permission for file.
    Returns:
      FileDefault FsPermission.

  - ### getCachePoolDefault

    public static FsPermission getCachePoolDefault()
    Get the default permission for cache pools.
    Returns:
      CachePoolDefault FsPermission.

  - ### valueOf

    public static FsPermission valueOf(String unixSymbolicPermission)
    Create a FsPermission from a Unix symbolic permission string
    Parameters:
      `unixSymbolicPermission` - e.g. "-rw-rw-rw-"
    Returns:
      FsPermission.

  - ### validateObject

    public void validateObject() throws InvalidObjectException
    Specified by:
      `validateObject` in interface `ObjectInputValidation`
    Throws:
      `InvalidObjectException`