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

All Known Implementing Classes:

AbstractFSBuilderImpl, FSDataOutputStreamBuilder, FutureDataInputStreamBuilderImpl, MultipartUploaderBuilderImpl

@InterfaceAudience.Public
 @InterfaceStability.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 and 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... values) Set a string array as mandatory option.
B	must(String key, String value) Set mandatory option to the Builder.
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... values) Set an array of string values as optional parameter for the Builder.
B	opt(String key, String value) Set optional Builder parameter.
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 Detail

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.