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(java.lang.String key, boolean value)	Set mandatory boolean option.
default B	must(java.lang.String key, double value)	Deprecated.
default B	must(java.lang.String key, float value)	Deprecated. use mustDouble(String, double) to set floating point.
default B	must(java.lang.String key, int value)	Set mandatory int option.
default B	must(java.lang.String key, long value)	Deprecated.
B	must(java.lang.String key, java.lang.String value)	Set mandatory option to the Builder.
B	must(java.lang.String key, java.lang.String... values)	Set a string array as mandatory option.
default B	mustDouble(java.lang.String key, double value)	Set mandatory double parameter for the Builder.
default B	mustLong(java.lang.String key, long value)	Set mandatory long parameter for the Builder.
default B	opt(java.lang.String key, boolean value)	Set optional boolean parameter for the Builder.
default B	opt(java.lang.String key, double value)	Deprecated. use optDouble(String, double)
default B	opt(java.lang.String key, float value)	Deprecated. use optDouble(String, double)
default B	opt(java.lang.String key, int value)	Set optional int parameter for the Builder.
default B	opt(java.lang.String key, long value)	Deprecated. use optLong(String, long) where possible.
B	opt(java.lang.String key, java.lang.String value)	Set optional Builder parameter.
B	opt(java.lang.String key, java.lang.String... values)	Set an array of string values as optional parameter for the Builder.
default B	optDouble(java.lang.String key, double value)	Set optional double parameter for the Builder.
default B	optLong(java.lang.String key, long value)	Set optional long parameter for the Builder.

Method Detail

opt

B opt(@Nonnull
      java.lang.String key,
      @Nonnull
      java.lang.String value)

Set optional Builder parameter.

Parameters:

key - key.

value - value.

Returns:

generic type B.

opt

default B opt(@Nonnull
              java.lang.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
              java.lang.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
              java.lang.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
              java.lang.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
              java.lang.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
      java.lang.String key,
      @Nonnull
      java.lang.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
                  java.lang.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
                    java.lang.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
       java.lang.String key,
       @Nonnull
       java.lang.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
               java.lang.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
               java.lang.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
               java.lang.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
               java.lang.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
               java.lang.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
       java.lang.String key,
       @Nonnull
       java.lang.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
                   java.lang.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
                     java.lang.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 java.lang.IllegalArgumentException,
        java.lang.UnsupportedOperationException,
        java.io.IOException

Instantiate the object which was being built.

Returns:

generic type S.

Throws:

java.lang.IllegalArgumentException - if the parameters are not valid.

java.lang.UnsupportedOperationException - if the filesystem does not support the specific operation.

java.io.IOException - on filesystem IO errors.