org.apache.beam.sdk.options

Class PipelineOptionsFactory

java.lang.Object

org.apache.beam.sdk.options.PipelineOptionsFactory

public class PipelineOptionsFactory
extends java.lang.Object

Constructs a PipelineOptions or any derived interface that is composable to any other derived interface of PipelineOptions via the PipelineOptions.as(java.lang.Class<T>) method. Being able to compose one derived interface of PipelineOptions to another has the following restrictions:

• Any property with the same name must have the same return type for all derived interfaces of PipelineOptions.
• Every bean property of any interface derived from PipelineOptions must have a getter and setter method.
• Every method must conform to being a getter or setter for a JavaBean.
• The derived interface of PipelineOptions must be composable with every interface registered with this factory.

See the JavaBeans specification for more details as to what constitutes a property.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PipelineOptionsFactory.Builder A fluent PipelineOptions builder.

Constructor Summary

Constructors

Constructor and Description
PipelineOptionsFactory()

Method Summary

Modifier and Type	Method and Description
static <T extends PipelineOptions> T	as(java.lang.Class<T> klass) Creates and returns an object that implements <T>.
static PipelineOptions	create() Creates and returns an object that implements PipelineOptions.
static java.util.List<org.apache.beam.model.jobmanagement.v1.JobApi.PipelineOptionDescriptor>	describe(java.util.Set<java.lang.Class<? extends PipelineOptions>> ifaces) Outputs the set of options available to be set for the passed in PipelineOptions interfaces.
static PipelineOptionsFactory.Builder	fromArgs(java.lang.String... args) Sets the command line arguments to parse when constructing the PipelineOptions.
static java.util.Set<java.lang.Class<? extends PipelineOptions>>	getRegisteredOptions()
static void	printHelp(java.io.PrintStream out) Outputs the set of registered options with the PipelineOptionsFactory with a description for each one if available to the output stream.
static void	printHelp(java.io.PrintStream out, java.lang.Class<? extends PipelineOptions> iface) Outputs the set of options available to be set for the passed in PipelineOptions interface.
static void	register(java.lang.Class<? extends PipelineOptions> iface) This registers the interface with this factory.
static void	resetCache() Resets the set of interfaces registered with this factory to the default state.
PipelineOptionsFactory.Builder	withValidation() After creation we will validate that <T> conforms to all the validation criteria.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PipelineOptionsFactory

public PipelineOptionsFactory()

Method Detail

create

public static PipelineOptions create()

Creates and returns an object that implements PipelineOptions. This sets the "appName" to the calling classes simple name.

Returns:

An object that implements PipelineOptions.

as

public static <T extends PipelineOptions> T as(java.lang.Class<T> klass)

Creates and returns an object that implements <T>. This sets the "appName" to the calling classes simple name.

Note that <T> must be composable with every registered interface with this factory. See PipelineOptionsFactory.Cache.validateWellFormed(Class, Set) for more details.

Returns:

An object that implements <T>.

fromArgs

public static PipelineOptionsFactory.Builder fromArgs(java.lang.String... args)

Sets the command line arguments to parse when constructing the PipelineOptions.

Example GNU style command line arguments:

   --project=MyProject (simple property, will set the "project" property to "MyProject")
   --readOnly=true (for boolean properties, will set the "readOnly" property to "true")
   --readOnly (shorthand for boolean properties, will set the "readOnly" property to "true")
   --x=1 --x=2 --x=3 (list style simple property, will set the "x" property to [1, 2, 3])
   --x=1,2,3 (shorthand list style simple property, will set the "x" property to [1, 2, 3])
   --complexObject='{"key1":"value1",...} (JSON format for all other complex types)
 

Simple properties are able to bound to String, Class, enums and Java primitives boolean, byte, short, int, long, float, double and their primitive wrapper classes.

Simple list style properties are able to be bound to boolean[], char[], short[], int[], long[], float[], double[], Class[], enum arrays, String[], and List<String>.

JSON format is required for all other types.

By default, strict parsing is enabled and arguments must conform to be either --booleanArgName or --argName=argValue. Strict parsing can be disabled with PipelineOptionsFactory.Builder.withoutStrictParsing(). Empty or null arguments will be ignored whether or not strict parsing is enabled.

Help information can be output to System.out by specifying --help as an argument. After help is printed, the application will exit. Specifying only --help will print out the list of registered options by invoking printHelp(PrintStream). Specifying --help=PipelineOptionsClassName will print out detailed usage information about the specifically requested PipelineOptions by invoking printHelp(PrintStream, Class).

withValidation

public PipelineOptionsFactory.Builder withValidation()

After creation we will validate that <T> conforms to all the validation criteria. See PipelineOptionsValidator.validate(Class, PipelineOptions) for more details about validation.

register

public static void register(java.lang.Class<? extends PipelineOptions> iface)

This registers the interface with this factory. This interface must conform to the following restrictions:

• Any property with the same name must have the same return type for all derived interfaces of PipelineOptions.
• Every bean property of any interface derived from PipelineOptions must have a getter and setter method.
• Every method must conform to being a getter or setter for a JavaBean.
• The derived interface of PipelineOptions must be composable with every interface registered with this factory.

Parameters:

iface - The interface object to manually register.

resetCache

@Experimental(value=UNSPECIFIED)
public static void resetCache()

Resets the set of interfaces registered with this factory to the default state.

IMPORTANT: this is marked as experimental because the correct usage of this method requires appropriate synchronization beyond the scope of this method.

See Also:

register(Class), Cache#Cache()

getRegisteredOptions

public static java.util.Set<java.lang.Class<? extends PipelineOptions>> getRegisteredOptions()

printHelp

public static void printHelp(java.io.PrintStream out)

Outputs the set of registered options with the PipelineOptionsFactory with a description for each one if available to the output stream. This output is pretty printed and meant to be human readable. This method will attempt to format its output to be compatible with a terminal window.

printHelp

public static void printHelp(java.io.PrintStream out,
                             java.lang.Class<? extends PipelineOptions> iface)

Outputs the set of options available to be set for the passed in PipelineOptions interface. The output is in a human readable format. The format is:

 OptionGroup:
     ... option group description ...

  --option1= <type> or list of valid enum choices
     Default: value (if available, see Default)
     ... option description ... (if available, see Description)
     Required groups (if available, see Validation.Required)
  --option2= <type> or list of valid enum choices
     Default: value (if available, see Default)
     ... option description ... (if available, see Description)
     Required groups (if available, see Validation.Required)
 

This method will attempt to format its output to be compatible with a terminal window.

describe

public static java.util.List<org.apache.beam.model.jobmanagement.v1.JobApi.PipelineOptionDescriptor> describe(java.util.Set<java.lang.Class<? extends PipelineOptions>> ifaces)

Outputs the set of options available to be set for the passed in PipelineOptions interfaces. The output for consumption of the job service client.