FSBuilder (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.fs, interface: FSBuilder

Package org.apache.hadoop.fs

# Interface FSBuilder<S,B extends FSBuilder<S,B>>

Type Parameters:
  `S` - Return type on the `build()` call.
  `B` - type of builder itself.

All Known Subinterfaces:
  `FutureDataInputStreamBuilder`, `MultipartUploaderBuilder<S,B>`

All Known Implementing Classes:
  `AbstractFSBuilderImpl`, `FileSystemMultipartUploaderBuilder`, `FSDataOutputStreamBuilder`, `FutureDataInputStreamBuilderImpl`, `MultipartUploaderBuilderImpl`

@Public @Unstable public interface FSBuilder<S,B extends FSBuilder<S,B>>
The base interface which various FileSystem FileContext Builder interfaces can extend, and which underlying implementations will then implement.

HADOOP-16202 expanded the opt() and must() arguments with operator overloading, but HADOOP-18724 identified mapping problems: passing a long value in to `opt()` could end up invoking `opt(string, double)`, which could then trigger parse failures.

To fix this without forcing existing code to break/be recompiled.

1. A new method to explicitly set a long value is added: `optLong(String, long)`
2. A new method to explicitly set a double value is added: `optLong(String, long)`
3. All of `opt(String, long)`, `opt(String, float)` and `opt(String, double)` invoke `optLong(String, long)`.
4. The same changes have been applied to `must()` methods.

The forwarding of existing double/float setters to the long setters ensure that existing code will link, but are guaranteed to always set a long value. If you need to write code which works correctly with all hadoop releases, covert the option to a string explicitly and then call `opt(String, String)` or `must(String, String)` as appropriate.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `S`
  `build()`
  Instantiate the object which was being built.
  `default B`
  `must(String key, boolean value)`
  Set mandatory boolean option.
  `default B`
  `must(String key, double value)`
  Deprecated.
  `default B`
  `must(String key, float value)`
  Deprecated.
  use `mustDouble(String, double)` to set floating point.
  `default B`
  `must(String key, int value)`
  Set mandatory int option.
  `default B`
  `must(String key, long value)`
  Deprecated.
  `B`
  `must(String key, String value)`
  Set mandatory option to the Builder.
  `B`
  `must(String key, String... values)`
  Set a string array as mandatory option.
  `default B`
  `mustDouble(String key, double value)`
  Set mandatory double parameter for the Builder.
  `default B`
  `mustLong(String key, long value)`
  Set mandatory long parameter for the Builder.
  `default B`
  `opt(String key, boolean value)`
  Set optional boolean parameter for the Builder.
  `default B`
  `opt(String key, double value)`
  Deprecated.
  use `optDouble(String, double)`
  `default B`
  `opt(String key, float value)`
  Deprecated.
  use `optDouble(String, double)`
  `default B`
  `opt(String key, int value)`
  Set optional int parameter for the Builder.
  `default B`
  `opt(String key, long value)`
  Deprecated.
  use `optLong(String, long)` where possible.
  `B`
  `opt(String key, String value)`
  Set optional Builder parameter.
  `B`
  `opt(String key, String... values)`
  Set an array of string values as optional parameter for the Builder.
  `default B`
  `optDouble(String key, double value)`
  Set optional double parameter for the Builder.
  `default B`
  `optLong(String key, long value)`
  Set optional long parameter for the Builder.

- ## Method Details

  - ### opt

    B opt(@Nonnull String key, @Nonnull String value)
    Set optional Builder parameter.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.

  - ### opt

    default B opt(@Nonnull String key, boolean value)
    Set optional boolean parameter for the Builder.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `opt(String, String)`

  - ### opt

    default B opt(@Nonnull String key, int value)
    Set optional int parameter for the Builder.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `opt(String, String)`

  - ### opt

    @Deprecated default B opt(@Nonnull String key, float value)
    Deprecated.
    use `optDouble(String, double)`
    This parameter is converted to a long and passed to `optLong(String, long)` -all decimal precision is lost.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `opt(String, String)`

  - ### opt

    default B opt(@Nonnull String key, long value)
    Deprecated.
    use `optLong(String, long)` where possible.
    Set optional long parameter for the Builder.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.

  - ### opt

    @Deprecated default B opt(@Nonnull String key, double value)
    Deprecated.
    use `optDouble(String, double)`
    Pass an optional double parameter for the Builder. This parameter is converted to a long and passed to `optLong(String, long)` -all decimal precision is lost.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `opt(String, String)`

  - ### opt

    B opt(@Nonnull String key, @Nonnull String... values)
    Set an array of string values as optional parameter for the Builder.
    Parameters:
      `key` - key.
      `values` - values.
    Returns:
      generic type B.
    See Also:
      - `opt(String, String)`

  - ### optLong

    default B optLong(@Nonnull String key, long value)
    Set optional long parameter for the Builder.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `opt(String, String)`

  - ### optDouble

    default B optDouble(@Nonnull String key, double value)
    Set optional double parameter for the Builder.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `opt(String, String)`

  - ### must

    B must(@Nonnull String key, @Nonnull String value)
    Set mandatory option to the Builder. If the option is not supported or unavailable, the client should expect `build()` throws IllegalArgumentException.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.

  - ### must

    default B must(@Nonnull String key, boolean value)
    Set mandatory boolean option.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `must(String, String)`

  - ### must

    default B must(@Nonnull String key, int value)
    Set mandatory int option.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `must(String, String)`

  - ### must

    @Deprecated default B must(@Nonnull String key, float value)
    Deprecated.
    use `mustDouble(String, double)` to set floating point.
    This parameter is converted to a long and passed to `mustLong(String, long)` -all decimal precision is lost.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.

  - ### must

    @Deprecated default B must(@Nonnull String key, long value)
    Deprecated.
    Set mandatory long option.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `must(String, String)`

  - ### must

    @Deprecated default B must(@Nonnull String key, double value)
    Deprecated.
    Set mandatory long option, despite passing in a floating point value.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `must(String, String)`

  - ### must

    B must(@Nonnull String key, @Nonnull String... values)
    Set a string array as mandatory option.
    Parameters:
      `key` - key.
      `values` - values.
    Returns:
      generic type B.
    See Also:
      - `must(String, String)`

  - ### mustLong

    default B mustLong(@Nonnull String key, long value)
    Set mandatory long parameter for the Builder.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `opt(String, String)`

  - ### mustDouble

    default B mustDouble(@Nonnull String key, double value)
    Set mandatory double parameter for the Builder.
    Parameters:
      `key` - key.
      `value` - value.
    Returns:
      generic type B.
    See Also:
      - `opt(String, String)`

  - ### build

    S build() throws IllegalArgumentException, UnsupportedOperationException, IOException
    Instantiate the object which was being built.
    Returns:
      generic type S.
    Throws:
      `IllegalArgumentException` - if the parameters are not valid.
      `UnsupportedOperationException` - if the filesystem does not support the specific operation.
      `IOException` - on filesystem IO errors.