org.apache.slider.core.main

Class ServiceLauncher<S extends org.apache.hadoop.service.Service>

java.lang.Object

org.apache.slider.core.main.ServiceLauncher<S>

All Implemented Interfaces:

Thread.UncaughtExceptionHandler, IrqHandler.Interrupted, LauncherExitCodes

public class ServiceLauncher<S extends org.apache.hadoop.service.Service>
extends Object
implements LauncherExitCodes, IrqHandler.Interrupted, Thread.UncaughtExceptionHandler

A class to launch any service by name. It's designed to be subclassed for custom entry points. Workflow

1. An instance of the class is created
2. If it implements RunService, it is given the binding args off the CLI
3. Its service.init() and service.start() methods are called.
4. If it implements RunService, runService() is called and its return code used as the exit code.
5. Otherwise: it waits for the service to stop, assuming in its start() method it begins work
6. If an exception returned an exit code, that becomes the exit code of the command.

Error and warning messages are logged to stderr. Why? If the classpath is wrong & logger configurations not on it, then no error messages by the started app will be seen and the caller is left trying to debug using exit codes.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	ServiceLauncher.ServiceForcedShutdown forced shutdown runnable.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ARG_CONF Name of the "--conf" argument.
static String	NAME
protected static int	PRIORITY
static String	USAGE_MESSAGE

Fields inherited from interface org.apache.slider.core.main.LauncherExitCodes

EXIT_CLIENT_INITIATED_SHUTDOWN, EXIT_COMMAND_ARGUMENT_ERROR, EXIT_CONFLICT, EXIT_CONNECTIVITY_PROBLEM, EXIT_EXCEPTION_THROWN, EXIT_FALSE, EXIT_FORBIDDEN, EXIT_FOUND, EXIT_INTERNAL_ERROR, EXIT_INTERRUPTED, EXIT_MOVED, EXIT_NOT_ACCEPTABLE, EXIT_NOT_FOUND, EXIT_NOT_MODIFIED, EXIT_OPERATION_NOT_ALLOWED, EXIT_OTHER_FAILURE, EXIT_SERVICE_UNAVAILABLE, EXIT_SUCCESS, EXIT_TASK_LAUNCH_FAILURE, EXIT_UNAUTHORIZE, EXIT_UNIMPLEMENTED, EXIT_UNSUPPORTED_VERSION, EXIT_USAGE

Constructor Summary

Constructors

Constructor and Description
ServiceLauncher(String serviceClassName) Create an instance of the launcher

Method Summary

Methods

Modifier and Type	Method and Description
protected org.apache.hadoop.util.ExitUtil.ExitException	convertToExitException(Throwable thrown) Convert the exception to one that can be handed off to ExitUtils; if it is of the write type it is passed throw as is.
protected void	error(String message, Throwable thrown) Report an error.
protected void	exit(org.apache.hadoop.util.ExitUtil.ExitException ee) Exit off an exception.
protected void	exit(int exitCode, String message) Exit the code.
static String[]	extractConfigurationArgs(org.apache.hadoop.conf.Configuration conf, List<String> args) Extract the configuration arguments and apply them to the configuration, building an array of processed arguments to hand down to the service.
org.apache.hadoop.conf.Configuration	getConfiguration() Get the configuration constructed from the command line arguments
S	getService() Get the service.
int	getServiceExitCode() The exit code from a successful service execution
String	getServiceName() Get the service name via Service.getName().
org.apache.hadoop.service.Service	instantiateService(org.apache.hadoop.conf.Configuration conf) Instantiate the service defined in serviceClassName .
void	interrupted(IrqHandler.InterruptData interruptData) The service has been interrupted -try to shut down the service.
int	launchService(org.apache.hadoop.conf.Configuration conf, String[] processedArgs, boolean addProcessHooks) Launch the service, by creating it, initing it, starting it and then maybe running it.
void	launchServiceAndExit(List<String> args) Parse the command line, building a configuration from it, then launch the service and wait for it to finish.
org.apache.hadoop.util.ExitUtil.ExitException	launchServiceRobustly(org.apache.hadoop.conf.Configuration conf, String[] processedArgs) Launch a service catching all exceptions and downgrading them to exit codes after logging.
static void	main(String[] args) This is the main entry point for the service launcher.
protected void	registerInterruptHandler() Register this class as the handler for the control-C interrupt.
static void	serviceMain(List<String> argsList) The real main function, which takes the arguments as a list arg 0 must be the service classname
static String	startupShutdownMessage(String classname, List<String> args) Build a log message for starting up and shutting down.
String	toString()
void	uncaughtException(Thread thread, Throwable exception) Uncaught exception handler.
protected void	warn(String text) Print a warning: currently this goes to stderr

Methods inherited from class java.lang.Object

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

Field Detail

PRIORITY

protected static final int PRIORITY

See Also:

Constant Field Values

NAME

public static final String NAME

See Also:

Constant Field Values

ARG_CONF

public static final String ARG_CONF

Name of the "--conf" argument.

See Also:

Constant Field Values

USAGE_MESSAGE

public static final String USAGE_MESSAGE

See Also:

Constant Field Values

Constructor Detail

ServiceLauncher

public ServiceLauncher(String serviceClassName)

Create an instance of the launcher

Parameters:

serviceClassName - classname of the service

Method Detail

getService

public S getService()

Get the service. Null until and unless launchService(Configuration, String[], boolean) has completed

Returns:

the service

getConfiguration

public org.apache.hadoop.conf.Configuration getConfiguration()

Get the configuration constructed from the command line arguments

Returns:

the configuration used to create the service

getServiceExitCode

public int getServiceExitCode()

The exit code from a successful service execution

Returns:

the exit code.

toString

public String toString()

Overrides:

toString in class Object

launchService

public int launchService(org.apache.hadoop.conf.Configuration conf,
                String[] processedArgs,
                boolean addProcessHooks)
                  throws Throwable

Launch the service, by creating it, initing it, starting it and then maybe running it. RunService.bindArgs(Configuration, String...) is invoked on the service between creation and init. All exceptions that occur are propagated upwards. If the method returns a status code, it means that it got as far starting the service, and if it implements RunService, that the method RunService.runService() has completed. At this point, the service is returned by getService().

Parameters:

conf - configuration

processedArgs - arguments after the configuration parameters have been stripped out.

addProcessHooks - should process failure handlers be added to terminate this service on shutdown. Tests should set this to false.

Throws:

ClassNotFoundException - classname not on the classpath

IllegalAccessException - not allowed at the class

InstantiationException - not allowed to instantiate it

InterruptedException - thread interrupted

Throwable - any other failure

instantiateService

public org.apache.hadoop.service.Service instantiateService(org.apache.hadoop.conf.Configuration conf)
                                                     throws ClassNotFoundException,
                                                            InstantiationException,
                                                            IllegalAccessException,
                                                            org.apache.hadoop.util.ExitUtil.ExitException,
                                                            NoSuchMethodException,
                                                            InvocationTargetException

Instantiate the service defined in serviceClassName . Sets the configuration field to the configuration, and service to the service.

Parameters:

conf - configuration to use

Throws:

ClassNotFoundException - classname not on the classpath

IllegalAccessException - not allowed at the class

InstantiationException - not allowed to instantiate it

org.apache.hadoop.util.ExitUtil.ExitException

NoSuchMethodException

InvocationTargetException

registerInterruptHandler

protected void registerInterruptHandler()

Register this class as the handler for the control-C interrupt. Can be overridden for testing.

interrupted

public void interrupted(IrqHandler.InterruptData interruptData)

The service has been interrupted -try to shut down the service. Give the service time to do this before the exit operation is called

Specified by:

interrupted in interface IrqHandler.Interrupted

Parameters:

interruptData - the interrupted data.

uncaughtException

public void uncaughtException(Thread thread,
                     Throwable exception)

Uncaught exception handler. If an error is raised: shutdown The state of the system is unknown at this point -attempting a clean shutdown is dangerous. Instead: exit

Specified by:

uncaughtException in interface Thread.UncaughtExceptionHandler

Parameters:

thread - thread that failed

exception - exception

warn

protected void warn(String text)

Print a warning: currently this goes to stderr

Parameters:

text -

error

protected void error(String message,
         Throwable thrown)

Report an error. The message is printed to stderr; the exception is logged via the current logger.

Parameters:

message - message for the user

thrown - the exception thrown

exit

protected void exit(int exitCode,
        String message)

Exit the code. This is method can be overridden for testing, throwing an exception instead. Any subclassed method MUST raise an ExitUtil.ExitException instance. The service launcher code assumes that after this method is invoked, no other code in the same method is called.

Parameters:

exitCode - code to exit

exit

protected void exit(org.apache.hadoop.util.ExitUtil.ExitException ee)

Exit off an exception. This can be subclassed for testing

Parameters:

ee - exit exception

getServiceName

public String getServiceName()

Get the service name via Service.getName(). If the service is not instantiated, the classname is returned instead.

Returns:

the service name

launchServiceAndExit

public void launchServiceAndExit(List<String> args)

Parse the command line, building a configuration from it, then launch the service and wait for it to finish. finally, exit passing the status code to the #exit(int) method.

Parameters:

args - arguments to the service. arg[0] is assumed to be the service classname and is automatically

extractConfigurationArgs

public static String[] extractConfigurationArgs(org.apache.hadoop.conf.Configuration conf,
                                List<String> args)

Extract the configuration arguments and apply them to the configuration, building an array of processed arguments to hand down to the service.

Parameters:

conf - configuration to update

args - main arguments. args[0] is assumed to be the service classname and is skipped

Returns:

the processed list.

launchServiceRobustly

public org.apache.hadoop.util.ExitUtil.ExitException launchServiceRobustly(org.apache.hadoop.conf.Configuration conf,
                                                                  String[] processedArgs)

Launch a service catching all exceptions and downgrading them to exit codes after logging.

Parameters:

conf - configuration to use

processedArgs - command line after the launcher-specific arguments have been stripped out

Returns:

an exit exception, which will have a status code of 0 if it worked

convertToExitException

protected org.apache.hadoop.util.ExitUtil.ExitException convertToExitException(Throwable thrown)

Convert the exception to one that can be handed off to ExitUtils; if it is of the write type it is passed throw as is. If not, a new exception with the exit code LauncherExitCodes.EXIT_EXCEPTION_THROWN is created, with the argument thrown as the inner cause

Parameters:

thrown - the exception thrown

Returns:

an exception to terminate the process with

startupShutdownMessage

public static String startupShutdownMessage(String classname,
                            List<String> args)

Build a log message for starting up and shutting down. This was grabbed from the ToolRunner code.

Parameters:

classname - the class of the server

args - arguments

serviceMain

public static void serviceMain(List<String> argsList)

The real main function, which takes the arguments as a list arg 0 must be the service classname

Parameters:

argsList - the list of arguments

main

public static void main(String[] args)

This is the main entry point for the service launcher.

Parameters:

args - command line arguments.