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

All Known Implementing Classes:

AbstractFSBuilderImpl, 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.