org.apache.twill.api

Interface TwillPreparer

public interface TwillPreparer

This interface exposes methods to set up the Twill runtime environment and start a Twill application.

Method Summary

Modifier and Type	Method and Description
TwillPreparer	addJVMOptions(String options) This methods adds extra JVM options that will be passed to the java command line for every runnable of the application started through this TwillPreparer instance.
TwillPreparer	addLogHandler(LogHandler handler) Adds a LogHandler for receiving an application log.
TwillPreparer	addSecureStore(SecureStore secureStore) Adds security credentials for the runtime environment to gives application access to resources.
TwillPreparer	enableDebugging(boolean doSuspend, String... runnables) Enable debugging for runnables.
TwillPreparer	enableDebugging(String... runnables) Enable debugging for runnables, without suspending the virtual machine to wait for the debugger.
TwillPreparer	setClassLoader(String classLoaderClassName) Sets the class name of the ClassLoader to be used for loading twill and application classes for all containers.
TwillPreparer	setJVMOptions(String options) This methods sets the extra JVM options that will be passed to the java command line for every runnable of the application started through this TwillPreparer instance.
TwillPreparer	setJVMOptions(String runnableName, String options) This methods sets the extra JVM options that will be passed to the java command line for the given runnable of the application started through this TwillPreparer instance.
TwillPreparer	setLogLevel(LogEntry.Level logLevel) Deprecated. Use setLogLevels(Map) with key Logger.ROOT_LOGGER_NAME instead.
TwillPreparer	setLogLevels(Map<String,LogEntry.Level> logLevels) Set the log levels for requested logger names for Twill applications running in a container.
TwillPreparer	setLogLevels(String runnableName, Map<String,LogEntry.Level> logLevelsForRunnable) Set the log levels for requested logger names for a TwillRunnable.
TwillPreparer	setSchedulerQueue(String name) Sets the name of the scheduler queue to use.
TwillPreparer	setUser(String user) Deprecated. This method will be removed in future version.
TwillController	start() Starts the application.
TwillController	start(long timeout, TimeUnit timeoutUnit) Starts the application.
TwillPreparer	withApplicationArguments(Iterable<String> args) Sets the list of arguments that will be passed to the application.
TwillPreparer	withApplicationArguments(String... args) Sets the list of arguments that will be passed to the application.
TwillPreparer	withApplicationClassPaths(Iterable<String> classPaths) Adds the set of paths to the classpath on the target machine for ApplicationMaster and all runnables.
TwillPreparer	withApplicationClassPaths(String... classPaths) Adds the set of paths to the classpath on the target machine for ApplicationMaster and all runnables.
TwillPreparer	withArguments(String runnableName, Iterable<String> args) Sets the list of arguments that will be passed to the TwillRunnable identified by the given name.
TwillPreparer	withArguments(String runnableName, String... args) Sets the list of arguments that will be passed to the TwillRunnable identified by the given name.
TwillPreparer	withBundlerClassAcceptor(ClassAcceptor classAcceptor) Uses ClassAcceptor to determine the classes to include in the bundle jar for ApplicationMaster and all runnables.
TwillPreparer	withClassPaths(Iterable<String> classPaths) Adds the set of paths to the classpath on the target machine for all runnables.
TwillPreparer	withClassPaths(String... classPaths) Adds the set of paths to the classpath on the target machine for all runnables.
TwillPreparer	withConfiguration(Map<String,String> config) Overrides the default configuration with the given set of configurations.
TwillPreparer	withConfiguration(String runnableName, Map<String,String> config) Overrides the default configuration with the given set of configurations for the given runnable only.
TwillPreparer	withDependencies(Class<?>... classes) Adds extra classes that the application is dependent on and is not traceable from the application itself.
TwillPreparer	withDependencies(Iterable<Class<?>> classes) Adds extra classes that the application is dependent on and is not traceable from the application itself.
TwillPreparer	withEnv(Map<String,String> env) Adds the set of environment variables that will be set as container environment variables for all runnables.
TwillPreparer	withEnv(String runnableName, Map<String,String> env) Adds the set of environment variables that will be set as container environment variables for the given runnable.
TwillPreparer	withMaxRetries(String runnableName, int maxRetries) Sets the maximum number of times (per instance) a runnable will be retried if it exits without success.
TwillPreparer	withResources(Iterable<URI> resources) Adds resources that will be available through the ClassLoader of the runnables.
TwillPreparer	withResources(URI... resources) Adds resources that will be available through the ClassLoader of the runnables.

Method Detail

withConfiguration

TwillPreparer withConfiguration(Map<String,String> config)

Overrides the default configuration with the given set of configurations.

Parameters:

config - set of configurations to override

Returns:

This TwillPreparer

withConfiguration

TwillPreparer withConfiguration(String runnableName,
                                Map<String,String> config)

Overrides the default configuration with the given set of configurations for the given runnable only. This is useful to override configurations that affects runnables, such as Configs.Keys.JAVA_RESERVED_MEMORY_MB and Configs.Keys.HEAP_RESERVED_MIN_RATIO.

Parameters:

runnableName - Name of the TwillRunnable.

config - set of configurations to override

Returns:

This TwillPreparer

addLogHandler

TwillPreparer addLogHandler(LogHandler handler)

Adds a LogHandler for receiving an application log.

Parameters:

handler - The LogHandler.

Returns:

This TwillPreparer.

setUser

@Deprecated
TwillPreparer setUser(String user)

Deprecated. This method will be removed in future version.

Sets the user name that runs the application. Default value is get from "user.name" by calling System.getProperty(String).

Parameters:

user - User name

Returns:

This TwillPreparer.

setSchedulerQueue

TwillPreparer setSchedulerQueue(String name)

Sets the name of the scheduler queue to use.

Parameters:

name - Name of the scheduler queue

Returns:

This TwillPreparer.

setJVMOptions

TwillPreparer setJVMOptions(String options)

This methods sets the extra JVM options that will be passed to the java command line for every runnable of the application started through this TwillPreparer instance. This is intended for advance usage. All options will be passed unchanged to the java command line. Invalid options could cause application not able to start.

Parameters:

options - extra JVM options.

setJVMOptions

TwillPreparer setJVMOptions(String runnableName,
                            String options)

This methods sets the extra JVM options that will be passed to the java command line for the given runnable of the application started through this TwillPreparer instance. The options set for the given runnable will be appended to any global options set through the setJVMOptions(String) or addJVMOptions(String) method. This is intended for advance usage. All options will be passed unchanged to the java command line. Invalid options could cause application not able to start.

Parameters:

options - extra JVM options.

addJVMOptions

TwillPreparer addJVMOptions(String options)

This methods adds extra JVM options that will be passed to the java command line for every runnable of the application started through this TwillPreparer instance. This is intended for advance usage. All options will be passed unchanged to the java command line. Invalid options could cause application not able to start.

Parameters:

options - extra JVM options.

enableDebugging

TwillPreparer enableDebugging(String... runnables)

Enable debugging for runnables, without suspending the virtual machine to wait for the debugger. This replaces any previous debug settings.

Parameters:

runnables - the names of runnables to enable for debugging. If empty, it means all runnables.

enableDebugging

TwillPreparer enableDebugging(boolean doSuspend,
                              String... runnables)

Enable debugging for runnables. This replaces any previous debug settings.

Parameters:

doSuspend - whether the virtual machines should be supended until the debugger connects. This option allows to debug a container from the very beginning. Note that in that case, the container cannot notify the controller of its debug port until the debugger is attached - you must figure out where it is running using the YARN console or APIs.

runnables - the names of runnables to enable for debugging. If empty, it means all runnables.

withApplicationArguments

TwillPreparer withApplicationArguments(String... args)

Sets the list of arguments that will be passed to the application. The arguments can be retrieved from TwillContext.getApplicationArguments().

Parameters:

args - Array of arguments.

Returns:

This TwillPreparer.

withApplicationArguments

TwillPreparer withApplicationArguments(Iterable<String> args)

Sets the list of arguments that will be passed to the application. The arguments can be retrieved from TwillContext.getApplicationArguments().

Parameters:

args - Iterable of arguments.

Returns:

This TwillPreparer.

withArguments

TwillPreparer withArguments(String runnableName,
                            String... args)

Sets the list of arguments that will be passed to the TwillRunnable identified by the given name. The arguments can be retrieved from TwillContext.getArguments().

Parameters:

runnableName - Name of the TwillRunnable.

args - Array of arguments.

Returns:

This TwillPreparer.

withArguments

TwillPreparer withArguments(String runnableName,
                            Iterable<String> args)

Sets the list of arguments that will be passed to the TwillRunnable identified by the given name. The arguments can be retrieved from TwillContext.getArguments().

Parameters:

runnableName - Name of the TwillRunnable.

args - Iterable of arguments.

Returns:

This TwillPreparer.

withDependencies

TwillPreparer withDependencies(Class<?>... classes)

Adds extra classes that the application is dependent on and is not traceable from the application itself.

Returns:

This TwillPreparer.

See Also:

withDependencies(Iterable)

withDependencies

TwillPreparer withDependencies(Iterable<Class<?>> classes)

Adds extra classes that the application is dependent on and is not traceable from the application itself. E.g. Class name used in Class.forName(String).

Parameters:

classes - set of classes to add to dependency list for generating the deployment jar.

Returns:

This TwillPreparer.

withResources

TwillPreparer withResources(URI... resources)

Adds resources that will be available through the ClassLoader of the runnables.

Returns:

This TwillPreparer.

See Also:

withResources(Iterable)

withResources

TwillPreparer withResources(Iterable<URI> resources)

Adds resources that will be available through the ClassLoader of the runnables. Useful for adding extra resource files or libraries that are not traceable from the application itself. If the URI is a jar file, classes inside would be loadable by the ClassLoader. If the URI is a directory, everything underneath would be available.

Parameters:

resources - Set of URI to the resources.

Returns:

This TwillPreparer.

withClassPaths

TwillPreparer withClassPaths(String... classPaths)

Adds the set of paths to the classpath on the target machine for all runnables.

Returns:

This TwillPreparer

See Also:

withClassPaths(Iterable)

withClassPaths

TwillPreparer withClassPaths(Iterable<String> classPaths)

Adds the set of paths to the classpath on the target machine for all runnables. Note that the paths would be just added without verification.

Parameters:

classPaths - Set of classpaths

Returns:

This TwillPreparer

withEnv

TwillPreparer withEnv(Map<String,String> env)

Adds the set of environment variables that will be set as container environment variables for all runnables.

Parameters:

env - set of environment variables

Returns:

This TwillPreparer

withEnv

TwillPreparer withEnv(String runnableName,
                      Map<String,String> env)

Adds the set of environment variables that will be set as container environment variables for the given runnable. Environment variables set through this method has higher precedence than the one set through withEnv(Map) if there is a key clash.

Parameters:

runnableName - Name of the TwillRunnable.

env - set of environment variables

Returns:

This TwillPreparer

withApplicationClassPaths

TwillPreparer withApplicationClassPaths(String... classPaths)

Adds the set of paths to the classpath on the target machine for ApplicationMaster and all runnables.

Returns:

This TwillPreparer

withApplicationClassPaths

TwillPreparer withApplicationClassPaths(Iterable<String> classPaths)

Adds the set of paths to the classpath on the target machine for ApplicationMaster and all runnables.

Returns:

This TwillPreparer

withBundlerClassAcceptor

TwillPreparer withBundlerClassAcceptor(ClassAcceptor classAcceptor)

Uses ClassAcceptor to determine the classes to include in the bundle jar for ApplicationMaster and all runnables.

Parameters:

classAcceptor - to specify which classes to include in the bundle jar

Returns:

This TwillPreparer

withMaxRetries

TwillPreparer withMaxRetries(String runnableName,
                             int maxRetries)

Sets the maximum number of times (per instance) a runnable will be retried if it exits without success. The default behavior is to retry indefinitely.

Parameters:

runnableName - Name of the TwillRunnable.

maxRetries - maximum number of retries per instance

Returns:

This TwillPreparer

addSecureStore

TwillPreparer addSecureStore(SecureStore secureStore)

Adds security credentials for the runtime environment to gives application access to resources.

Parameters:

secureStore - Contains security token available for the runtime environment.

Returns:

This TwillPreparer.

setLogLevel

@Deprecated
TwillPreparer setLogLevel(LogEntry.Level logLevel)

Deprecated. Use setLogLevels(Map) with key Logger.ROOT_LOGGER_NAME instead.

Set the root log level for Twill applications in all containers.

Parameters:

logLevel - the LogEntry.Level that should be set. The level match the Logback levels.

Returns:

This TwillPreparer.

setLogLevels

TwillPreparer setLogLevels(Map<String,LogEntry.Level> logLevels)

Set the log levels for requested logger names for Twill applications running in a container. The log level of any logger cannot be null, if there is null value, a IllegalArgumentException will be thrown.

Parameters:

logLevels - The Map contains the requested logger names and log levels that need to be set.

Returns:

This TwillPreparer.

setLogLevels

TwillPreparer setLogLevels(String runnableName,
                           Map<String,LogEntry.Level> logLevelsForRunnable)

Set the log levels for requested logger names for a TwillRunnable. The log level of any logger cannot be null, if there is null value, a IllegalArgumentException will be thrown.

Parameters:

runnableName - The name of the runnable to set the log level.

logLevelsForRunnable - The Map contains the requested logger names and log levels that need to be set.

Returns:

This TwillPreparer.

setClassLoader

TwillPreparer setClassLoader(String classLoaderClassName)

Sets the class name of the ClassLoader to be used for loading twill and application classes for all containers. The ClassLoader class should have a public constructor that takes two parameters in the form of (URL[] urls, ClassLoader parentClassLoader). The first parameter is an array of URL that contains the list of URL for loading classes and resources; the second parameter is the parent ClassLoader.

Parameters:

classLoaderClassName - name of the ClassLoader class.

Returns:

This TwillPreparer.

start

TwillController start()

Starts the application. It's the same as calling start(long, TimeUnit) with timeout of 60 seconds.

Returns:

A TwillController for controlling the running application.

start

TwillController start(long timeout,
                      TimeUnit timeoutUnit)

Starts the application. The application must be started within the given timeout. An application may fail to start within a given time if there is insufficient resources.

Parameters:

timeout - maximum time to wait for the application to start

timeoutUnit - unit for the timeout

Returns:

A TwillController for controlling the running application.