CreateFlag (Apache Hadoop Main 3.5.0 API)
Description: declaration: package: org.apache.hadoop.fs, enum: CreateFlag

Package org.apache.hadoop.fs

# Enum Class CreateFlag

java.lang.Object
java.lang.Enum<CreateFlag>
org.apache.hadoop.fs.CreateFlag

All Implemented Interfaces:
  `Serializable`, `Comparable<CreateFlag>`, `Constable`

@Public @Evolving public enum CreateFlag extends Enum<CreateFlag>
CreateFlag specifies the file create semantic. Users can combine flags like:
`EnumSet.of(CreateFlag.CREATE, CreateFlag.APPEND)`

Use the CreateFlag as follows:

1. CREATE - to create a file if it does not exist, else throw FileAlreadyExists.
2. APPEND - to append to a file if it exists, else throw FileNotFoundException.
3. OVERWRITE - to truncate a file if it exists, else throw FileNotFoundException.
4. CREATE|APPEND - to create a file if it does not exist, else append to an existing file.
5. CREATE|OVERWRITE - to create a file if it does not exist, else overwrite an existing file.
6. SYNC_BLOCK - to force closed blocks to the disk device. In addition `Syncable.hsync()` should be called after each write, if true synchronous behavior is required.
7. LAZY_PERSIST - Create the block on transient storage (RAM) if available.
8. APPEND_NEWBLOCK - Append data to a new block instead of end of the last partial block.

Following combinations are not valid and will result in `HadoopIllegalArgumentException`:

1. APPEND|OVERWRITE
2. CREATE|APPEND|OVERWRITE

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class java.lang.Enum

  `Enum.EnumDesc<E extends Enum<E>>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `APPEND`
  Append to a file.
  `CREATE`
  Create a file.
  `IGNORE_CLIENT_LOCALITY`
  Advise that the first block replica NOT take into account DataNode locality.
  `LAZY_PERSIST`
  Create the block on transient storage (RAM) if available.
  `NEW_BLOCK`
  Append data to a new block instead of the end of the last partial block.
  `NO_LOCAL_RACK`
  Advise that a block replica NOT be written to the local rack DataNode where 'local' means the same rack as the client is being run on.
  `NO_LOCAL_WRITE`
  Advise that a block replica NOT be written to the local DataNode where 'local' means the same host as the client is being run on.
  `OVERWRITE`
  Truncate/overwrite a file.
  `SHOULD_REPLICATE`
  Enforce the file to be a replicated file, no matter what its parent directory's replication or erasure coding policy is.
  `SYNC_BLOCK`
  Force closed blocks to disk.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `validate(Object path, boolean pathExists, EnumSet<CreateFlag> flag)`
  Validate the CreateFlag for create operation
  `static void`
  `validate(EnumSet<CreateFlag> flag)`
  Validate the CreateFlag and throw exception if it is invalid
  `static void`
  `validateForAppend(EnumSet<CreateFlag> flag)`
  Validate the CreateFlag for the append operation.
  `static CreateFlag`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static CreateFlag[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.

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

  `clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

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

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Enum Constant Details

  - ### CREATE

    public static final CreateFlag CREATE
    Create a file. See javadoc for more description already exists

  - ### OVERWRITE

    public static final CreateFlag OVERWRITE
    Truncate/overwrite a file. Same as POSIX O_TRUNC. See javadoc for description.

  - ### APPEND

    public static final CreateFlag APPEND
    Append to a file. See javadoc for more description.

  - ### SYNC_BLOCK

    public static final CreateFlag SYNC_BLOCK
    Force closed blocks to disk. Similar to POSIX O_SYNC. See javadoc for description.

  - ### LAZY_PERSIST

    public static final CreateFlag LAZY_PERSIST
    Create the block on transient storage (RAM) if available. If transient storage is unavailable then the block will be created on disk. HDFS will make a best effort to lazily write these files to persistent storage, however file contents may be lost at any time due to process/ node restarts, hence there is no guarantee of data durability. This flag must only be used for intermediate data whose loss can be tolerated by the application.

  - ### NEW_BLOCK

    public static final CreateFlag NEW_BLOCK
    Append data to a new block instead of the end of the last partial block. This is only useful for APPEND.

  - ### NO_LOCAL_WRITE

    @LimitedPrivate("HBase") public static final CreateFlag NO_LOCAL_WRITE
    Advise that a block replica NOT be written to the local DataNode where 'local' means the same host as the client is being run on.

  - ### SHOULD_REPLICATE

    public static final CreateFlag SHOULD_REPLICATE
    Enforce the file to be a replicated file, no matter what its parent directory's replication or erasure coding policy is.

  - ### IGNORE_CLIENT_LOCALITY

    public static final CreateFlag IGNORE_CLIENT_LOCALITY
    Advise that the first block replica NOT take into account DataNode locality. The first block replica should be placed randomly within the cluster. Subsequent block replicas should follow DataNode locality rules.

  - ### NO_LOCAL_RACK

    public static final CreateFlag NO_LOCAL_RACK
    Advise that a block replica NOT be written to the local rack DataNode where 'local' means the same rack as the client is being run on.

- ## Method Details

  - ### values

    public static CreateFlag[] values()
    Returns an array containing the constants of this enum class, in the order they are declared.
    Returns:
      an array containing the constants of this enum class, in the order they are declared

  - ### valueOf

    public static CreateFlag valueOf(String name)
    Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
    Parameters:
      `name` - the name of the enum constant to be returned.
    Returns:
      the enum constant with the specified name
    Throws:
      `IllegalArgumentException` - if this enum class has no constant with the specified name
      `NullPointerException` - if the argument is null

  - ### validate

    public static void validate(EnumSet<CreateFlag> flag)
    Validate the CreateFlag and throw exception if it is invalid
    Parameters:
      `flag` - set of CreateFlag
    Throws:
      `HadoopIllegalArgumentException` - if the CreateFlag is invalid

  - ### validate

    public static void validate(Object path, boolean pathExists, EnumSet<CreateFlag> flag) throws IOException
    Validate the CreateFlag for create operation
    Parameters:
      `path` - Object representing the path; usually String or `Path`
      `pathExists` - pass true if the path exists in the file system
      `flag` - set of CreateFlag
    Throws:
      `IOException` - on error
      `HadoopIllegalArgumentException` - if the CreateFlag is invalid

  - ### validateForAppend

    public static void validateForAppend(EnumSet<CreateFlag> flag)
    Validate the CreateFlag for the append operation. The flag must contain APPEND, and cannot contain OVERWRITE.
    Parameters:
      `flag` - enum set flag.