org.apache.hadoop.fs

## Enum CreateFlag

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

- All Implemented Interfaces:
    Serializable, Comparable<CreateFlag>

      @InterfaceAudience.Public
       @InterfaceStability.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
  ``

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant and 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_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

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

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

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

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

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

- - ### Enum Constant Detail

    - #### 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

          @InterfaceAudience.LimitedPrivate(value="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.

  - ### Method Detail

    - #### values

          public static CreateFlag[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (CreateFlag c : CreateFlag.values())
              System.out.println(c);

      Returns:
        an array containing the constants of this enum type, in the order they are declared

    - #### valueOf

          public static CreateFlag valueOf(String name)

      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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 type 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.

Copyright © 2022 Apache Software Foundation. All rights reserved.