| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc (1.8.0_292) on Tue Jun 15 06:02:23 GMT 2021 --> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>org.apache.hadoop.service.launcher (Apache Hadoop Common 3.3.1 API)</title> |
| <meta name="date" content="2021-06-15"> |
| <link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="Style"> |
| <script type="text/javascript" src="../../../../../script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="org.apache.hadoop.service.launcher (Apache Hadoop Common 3.3.1 API)"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-use.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../../org/apache/hadoop/service/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../../org/apache/hadoop/tools/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../../index.html?org/apache/hadoop/service/launcher/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 title="Package" class="title">Package org.apache.hadoop.service.launcher</h1> |
| <div class="docSummary"> |
| <div class="block">This package contains classes, interfaces and exceptions to launch |
| YARN services from the command line.</div> |
| </div> |
| <p>See: <a href="#package.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Interface Summary table, listing interfaces, and an explanation"> |
| <caption><span>Interface Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Interface</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/IrqHandler.Interrupted.html" title="interface in org.apache.hadoop.service.launcher">IrqHandler.Interrupted</a></td> |
| <td class="colLast"> |
| <div class="block">Callback issues on an interrupt.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html" title="interface in org.apache.hadoop.service.launcher">LaunchableService</a></td> |
| <td class="colLast"> |
| <div class="block">An interface which services can implement to have their |
| execution managed by the ServiceLauncher.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/LauncherArguments.html" title="interface in org.apache.hadoop.service.launcher">LauncherArguments</a></td> |
| <td class="colLast"> |
| <div class="block">Standard launcher arguments.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/LauncherExitCodes.html" title="interface in org.apache.hadoop.service.launcher">LauncherExitCodes</a></td> |
| <td class="colLast"> |
| <div class="block">Common Exit codes.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation"> |
| <caption><span>Class Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Class</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/AbstractLaunchableService.html" title="class in org.apache.hadoop.service.launcher">AbstractLaunchableService</a></td> |
| <td class="colLast"> |
| <div class="block">Subclass of <a href="../../../../../org/apache/hadoop/service/AbstractService.html" title="class in org.apache.hadoop.service"><code>AbstractService</code></a> that provides basic implementations |
| of the <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html" title="interface in org.apache.hadoop.service.launcher"><code>LaunchableService</code></a> methods.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/HadoopUncaughtExceptionHandler.html" title="class in org.apache.hadoop.service.launcher">HadoopUncaughtExceptionHandler</a></td> |
| <td class="colLast"> |
| <div class="block">This class is intended to be installed by calling |
| <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.html?is-external=true#setDefaultUncaughtExceptionHandler-java.lang.Thread.UncaughtExceptionHandler-" title="class or interface in java.lang"><code>Thread.setDefaultUncaughtExceptionHandler(UncaughtExceptionHandler)</code></a> |
| in the main entry point.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/InterruptEscalator.ServiceForcedShutdown.html" title="class in org.apache.hadoop.service.launcher">InterruptEscalator.ServiceForcedShutdown</a></td> |
| <td class="colLast"> |
| <div class="block">Forced shutdown runnable.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/IrqHandler.InterruptData.html" title="class in org.apache.hadoop.service.launcher">IrqHandler.InterruptData</a></td> |
| <td class="colLast"> |
| <div class="block">Interrupt data to pass on.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/ServiceLauncher.html" title="class in org.apache.hadoop.service.launcher">ServiceLauncher</a><S extends <a href="../../../../../org/apache/hadoop/service/Service.html" title="interface in org.apache.hadoop.service">Service</a>></td> |
| <td class="colLast"> |
| <div class="block">A class to launch any YARN service by name.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/ServiceLauncher.MinimalGenericOptionsParser.html" title="class in org.apache.hadoop.service.launcher">ServiceLauncher.MinimalGenericOptionsParser</a></td> |
| <td class="colLast"> |
| <div class="block">A generic options parser which does not parse any of the traditional |
| Hadoop options.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Exception Summary table, listing exceptions, and an explanation"> |
| <caption><span>Exception Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Exception</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/hadoop/service/launcher/ServiceLaunchException.html" title="class in org.apache.hadoop.service.launcher">ServiceLaunchException</a></td> |
| <td class="colLast"> |
| <div class="block">A service launch exception that includes an exit code.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| </ul> |
| <a name="package.description"> |
| <!-- --> |
| </a> |
| <h2 title="Package org.apache.hadoop.service.launcher Description">Package org.apache.hadoop.service.launcher Description</h2> |
| <div class="block">This package contains classes, interfaces and exceptions to launch |
| YARN services from the command line. |
| |
| <h2>Key Features</h2> |
| |
| <p> |
| <b>General purpose YARN service launcher</b>:<p> |
| The <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLauncher.html" title="class in org.apache.hadoop.service.launcher"><code>ServiceLauncher</code></a> class parses |
| a command line, then instantiates and launches the specified YARN service. It |
| then waits for the service to finish, converting any exceptions raised or |
| exit codes returned into an exit code for the (then exited) process. |
| <p> |
| This class is designed be invokable from the static |
| <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLauncher.html#main-java.lang.String:A-"><code>ServiceLauncher.main(String[])</code></a> |
| method, or from <code>main(String[])</code> methods implemented by |
| other classes which provide their own entry points. |
| |
| |
| <p> |
| <b>Extended YARN Service Interface</b>:<p> |
| The <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html" title="interface in org.apache.hadoop.service.launcher"><code>LaunchableService</code></a> interface |
| extends <a href="../../../../../org/apache/hadoop/service/Service.html" title="interface in org.apache.hadoop.service"><code>Service</code></a> with methods to pass |
| down the CLI arguments and to execute an operation without having to |
| spawn a thread in the <a href="../../../../../org/apache/hadoop/service/Service.html#start--"><code>Service.start()</code></a> phase. |
| |
| |
| <p> |
| <b>Standard Exit codes</b>:<p> |
| <a href="../../../../../org/apache/hadoop/service/launcher/LauncherExitCodes.html" title="interface in org.apache.hadoop.service.launcher"><code>LauncherExitCodes</code></a> |
| defines a set of exit codes that can be used by services to standardize |
| exit causes. |
| |
| <p> |
| <b>Escalated shutdown</b>:<p> |
| The <code>ServiceShutdownHook</code> |
| shuts down any service via the hadoop shutdown mechanism. |
| The <code>InterruptEscalator</code> can be |
| registered to catch interrupts, triggering the shutdown -and forcing a JVM |
| exit if it times out or a second interrupt is received. |
| |
| <p><b>Tests:</b><p> test cases include interrupt handling and |
| lifecycle failures. |
| |
| <h2>Launching a YARN Service</h2> |
| |
| The Service Launcher can launch <i>any YARN service</i>. |
| It will instantiate the service classname provided, using the no-args |
| constructor, or if no such constructor is available, it will fall back |
| to a constructor with a single <code>String</code> parameter, |
| passing the service name as the parameter value. |
| <p> |
| |
| The launcher will initialize the service via |
| <a href="../../../../../org/apache/hadoop/service/Service.html#init-org.apache.hadoop.conf.Configuration-"><code>Service.init(Configuration)</code></a>, |
| then start it via its <a href="../../../../../org/apache/hadoop/service/Service.html#start--"><code>Service.start()</code></a> method. |
| It then waits indefinitely for the service to stop. |
| <p> |
| After the service has stopped, a non-null value of |
| <a href="../../../../../org/apache/hadoop/service/Service.html#getFailureCause--"><code>Service.getFailureCause()</code></a> is interpreted |
| as a failure, and, if it didn't happen during the stop phase (i.e. when |
| <a href="../../../../../org/apache/hadoop/service/Service.html#getFailureState--"><code>Service.getFailureState()</code></a> is not |
| <code>STATE.STOPPED</code>, escalated into a non-zero return code). |
| <p> |
| |
| To view the workflow in sequence, it is: |
| <ol> |
| <li>(prepare configuration files —covered later)</li> |
| <li>instantiate service via its empty or string constructor</li> |
| <li>call <a href="../../../../../org/apache/hadoop/service/Service.html#init-org.apache.hadoop.conf.Configuration-"><code>Service.init(Configuration)</code></a></li> |
| <li>call <a href="../../../../../org/apache/hadoop/service/Service.html#start--"><code>Service.start()</code></a></li> |
| <li>call |
| <a href="../../../../../org/apache/hadoop/service/Service.html#waitForServiceToStop-long-"><code>Service.waitForServiceToStop(long)</code></a></li> |
| <li>If an exception was raised: propagate it</li> |
| <li>If an exception was recorded in |
| <a href="../../../../../org/apache/hadoop/service/Service.html#getFailureCause--"><code>Service.getFailureCause()</code></a> |
| while the service was running: propagate it.</li> |
| </ol> |
| |
| For a service to be fully compatible with this launch model, it must |
| <ul> |
| <li>Start worker threads, processes and executors in its |
| <a href="../../../../../org/apache/hadoop/service/Service.html#start--"><code>Service.start()</code></a> method</li> |
| <li>Terminate itself via a call to |
| <a href="../../../../../org/apache/hadoop/service/Service.html#stop--"><code>Service.stop()</code></a> |
| in one of these asynchronous methods.</li> |
| </ul> |
| |
| If a service does not stop itself, <i>ever</i>, then it can be launched |
| as a long-lived daemon. |
| The service launcher will never terminate, but neither will the service. |
| The service launcher does register signal handlers to catch <code>kill</code> |
| and control-C signals —calling <code>stop()</code> on the service when |
| signaled. |
| This means that a daemon service <i>may</i> get a warning and time to shut |
| down. |
| |
| <p> |
| To summarize: provided a service launches its long-lived threads in its Service |
| <code>start()</code> method, the service launcher can create it, configure it |
| and start it, triggering shutdown when signaled. |
| |
| What these services can not do is get at the command line parameters or easily |
| propagate exit codes (there is a way covered later). These features require |
| some extensions to the base <code>Service</code> interface: <i>the Launchable |
| Service</i>. |
| |
| <h2>Launching a Launchable YARN Service</h2> |
| |
| A Launchable YARN Service is a YARN service which implements the interface |
| <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html" title="interface in org.apache.hadoop.service.launcher"><code>LaunchableService</code></a>. |
| <p> |
| It adds two methods to the service interface —and hence two new features: |
| |
| <ol> |
| <li>Access to the command line passed to the service launcher </li> |
| <li>A blocking <code>int execute()</code> method which can return the exit |
| code for the application.</li> |
| </ol> |
| |
| This design is ideal for implementing services which parse the command line, |
| and which execute short-lived applications. For example, end user |
| commands can be implemented as such services, thus integrating with YARN's |
| workflow and <code>YarnClient</code> client-side code. |
| |
| <p> |
| It can just as easily be used for implementing long-lived services that |
| parse the command line -it just becomes the responsibility of the |
| service to decide when to return from the <code>execute()</code> method. |
| It doesn't even need to <code>stop()</code> itself; the launcher will handle |
| that if necessary. |
| <p> |
| The <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html" title="interface in org.apache.hadoop.service.launcher"><code>LaunchableService</code></a> interface |
| extends <a href="../../../../../org/apache/hadoop/service/Service.html" title="interface in org.apache.hadoop.service"><code>Service</code></a> with two new methods. |
| |
| <p> |
| <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html#bindArgs-org.apache.hadoop.conf.Configuration-java.util.List-"><code>LaunchableService.bindArgs(Configuration, List)</code></a> |
| provides the <code>main(String args[])</code> arguments as a list, after any |
| processing by the Service Launcher to extract configuration file references. |
| This method <i>is called before |
| <a href="../../../../../org/apache/hadoop/service/Service.html#init-org.apache.hadoop.conf.Configuration-"><code>Service.init(Configuration)</code></a>.</i> |
| This is by design: it allows the arguments to be parsed before the service is |
| initialized, thus allowing services to tune their configuration data before |
| passing it to any superclass in that <code>init()</code> method. |
| To make this operation even simpler, the |
| <a href="../../../../../org/apache/hadoop/conf/Configuration.html" title="class in org.apache.hadoop.conf"><code>Configuration</code></a> that is to be passed in |
| is provided as an argument. |
| This reference passed in is the initial configuration for this service; |
| the one that will be passed to the init operation. |
| |
| In |
| <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html#bindArgs-org.apache.hadoop.conf.Configuration-java.util.List-"><code>LaunchableService.bindArgs(Configuration, List)</code></a>, |
| a Launchable Service may manipulate this configuration by setting or removing |
| properties. It may also create a new <code>Configuration</code> instance |
| which may be needed to trigger the injection of HDFS or YARN resources |
| into the default resources of all Configurations. |
| If the return value of the method call is a configuration |
| reference (as opposed to a null value), the returned value becomes that |
| passed in to the <code>init()</code> method. |
| <p> |
| After the <code>bindArgs()</code> processing, the service's <code>init()</code> |
| and <code>start()</code> methods are called, as usual. |
| <p> |
| At this point, rather than block waiting for the service to terminate (as |
| is done for a basic service), the method |
| <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html#execute--"><code>LaunchableService.execute()</code></a> |
| is called. |
| This is a method expected to block until completed, returning the intended |
| application exit code of the process when it does so. |
| <p> |
| After this <code>execute()</code> operation completes, the |
| service is stopped and exit codes generated. Any exception raised |
| during the <code>execute()</code> method takes priority over any exit codes |
| returned by the method. This allows services to signal failures simply |
| by raising exceptions with exit codes. |
| <p> |
| |
| <p> |
| To view the workflow in sequence, it is: |
| <ol> |
| <li>(prepare configuration files —covered later)</li> |
| <li>instantiate service via its empty or string constructor</li> |
| <li>call <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html#bindArgs-org.apache.hadoop.conf.Configuration-java.util.List-"><code>LaunchableService.bindArgs(Configuration, List)</code></a></li> |
| <li>call <a href="../../../../../org/apache/hadoop/service/Service.html#init-org.apache.hadoop.conf.Configuration-"><code>Service.init(Configuration)</code></a> with the existing config, |
| or any new one returned by |
| <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html#bindArgs-org.apache.hadoop.conf.Configuration-java.util.List-"><code>LaunchableService.bindArgs(Configuration, List)</code></a></li> |
| <li>call <a href="../../../../../org/apache/hadoop/service/Service.html#start--"><code>Service.start()</code></a></li> |
| <li>call <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html#execute--"><code>LaunchableService.execute()</code></a></li> |
| <li>call <a href="../../../../../org/apache/hadoop/service/Service.html#stop--"><code>Service.stop()</code></a></li> |
| <li>The return code from |
| <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html#execute--"><code>LaunchableService.execute()</code></a> |
| becomes the exit code of the process, unless overridden by an exception.</li> |
| <li>If an exception was raised in this workflow: propagate it</li> |
| <li>If an exception was recorded in |
| <a href="../../../../../org/apache/hadoop/service/Service.html#getFailureCause--"><code>Service.getFailureCause()</code></a> |
| while the service was running: propagate it.</li> |
| </ol> |
| |
| |
| <h2>Exit Codes and Exceptions</h2> |
| |
| <p> |
| For a basic service, the return code is 0 unless an exception |
| was raised. |
| <p> |
| For a <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html" title="interface in org.apache.hadoop.service.launcher"><code>LaunchableService</code></a>, the return |
| code is the number returned from the |
| <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html#execute--"><code>LaunchableService.execute()</code></a> |
| operation, again, unless overridden an exception was raised. |
| |
| <p> |
| Exceptions are converted into exit codes -but rather than simply |
| have a "something went wrong" exit code, exceptions <i>may</i> |
| provide exit codes which will be extracted and used as the return code. |
| This enables Launchable Services to use exceptions as a way |
| of returning error codes to signal failures and for |
| normal Services to return any error code at all. |
| |
| <p> |
| Any exception which implements the |
| <a href="../../../../../org/apache/hadoop/util/ExitCodeProvider.html" title="interface in org.apache.hadoop.util"><code>ExitCodeProvider</code></a> |
| interface is considered be a provider of the exit code: the method |
| <a href="../../../../../org/apache/hadoop/util/ExitCodeProvider.html#getExitCode--"><code>ExitCodeProvider.getExitCode()</code></a> |
| will be called on the caught exception to generate the return code. |
| This return code and the message in the exception will be used to |
| generate an instance of |
| <a href="../../../../../org/apache/hadoop/util/ExitUtil.ExitException.html" title="class in org.apache.hadoop.util"><code>ExitUtil.ExitException</code></a> |
| which can be passed down to |
| <code>ExitUtil.terminate(ExitUtil.ExitException)</code> |
| to trigger a JVM exit. The initial exception will be used as the cause |
| of the <a href="../../../../../org/apache/hadoop/util/ExitUtil.ExitException.html" title="class in org.apache.hadoop.util"><code>ExitUtil.ExitException</code></a>. |
| |
| <p> |
| If the exception is already an instance or subclass of |
| <a href="../../../../../org/apache/hadoop/util/ExitUtil.ExitException.html" title="class in org.apache.hadoop.util"><code>ExitUtil.ExitException</code></a>, it is passed |
| directly to |
| <code>ExitUtil.terminate(ExitUtil.ExitException)</code> |
| without any conversion. |
| One such subclass, |
| <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLaunchException.html" title="class in org.apache.hadoop.service.launcher"><code>ServiceLaunchException</code></a> |
| may be useful: it includes formatted exception message generation. |
| It also declares that it extends the |
| <a href="../../../../../org/apache/hadoop/service/launcher/LauncherExitCodes.html" title="interface in org.apache.hadoop.service.launcher"><code>LauncherExitCodes</code></a> |
| interface listing common exception codes. These are exception codes |
| that can be raised by the <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLauncher.html" title="class in org.apache.hadoop.service.launcher"><code>ServiceLauncher</code></a> |
| itself to indicate problems during parsing the command line, creating |
| the service instance and the like. There are also some common exit codes |
| for Hadoop/YARN service failures, such as |
| <a href="../../../../../org/apache/hadoop/service/launcher/LauncherExitCodes.html#EXIT_UNAUTHORIZED"><code>LauncherExitCodes.EXIT_UNAUTHORIZED</code></a>. |
| Note that <a href="../../../../../org/apache/hadoop/util/ExitUtil.ExitException.html" title="class in org.apache.hadoop.util"><code>ExitUtil.ExitException</code></a> itself |
| implements <a href="../../../../../org/apache/hadoop/util/ExitCodeProvider.html#getExitCode--"><code>ExitCodeProvider.getExitCode()</code></a> |
| |
| <p> |
| If an exception does not implement |
| <a href="../../../../../org/apache/hadoop/util/ExitCodeProvider.html#getExitCode--"><code>ExitCodeProvider.getExitCode()</code></a>, |
| it will be wrapped in an <a href="../../../../../org/apache/hadoop/util/ExitUtil.ExitException.html" title="class in org.apache.hadoop.util"><code>ExitUtil.ExitException</code></a> |
| with the exit code |
| <a href="../../../../../org/apache/hadoop/service/launcher/LauncherExitCodes.html#EXIT_EXCEPTION_THROWN"><code>LauncherExitCodes.EXIT_EXCEPTION_THROWN</code></a>. |
| |
| <p> |
| To view the exit code extraction in sequence, it is: |
| <ol> |
| <li>If no exception was triggered by a basic service, a |
| <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLaunchException.html" title="class in org.apache.hadoop.service.launcher"><code>ServiceLaunchException</code></a> with an |
| exit code of 0 is created.</li> |
| |
| <li>For a LaunchableService, the exit code is the result of <code>execute()</code> |
| Again, a <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLaunchException.html" title="class in org.apache.hadoop.service.launcher"><code>ServiceLaunchException</code></a> |
| with a return code of 0 is created. |
| </li> |
| |
| <li>Otherwise, if the exception is an instance of <code>ExitException</code>, |
| it is returned as the service terminating exception.</li> |
| |
| <li>If the exception implements <a href="../../../../../org/apache/hadoop/util/ExitCodeProvider.html" title="interface in org.apache.hadoop.util"><code>ExitCodeProvider</code></a>, |
| its exit code and <code>getMessage()</code> value become the exit exception.</li> |
| |
| <li>Otherwise, it is wrapped as a |
| <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLaunchException.html" title="class in org.apache.hadoop.service.launcher"><code>ServiceLaunchException</code></a> |
| with the exit code |
| <a href="../../../../../org/apache/hadoop/service/launcher/LauncherExitCodes.html#EXIT_EXCEPTION_THROWN"><code>LauncherExitCodes.EXIT_EXCEPTION_THROWN</code></a> |
| to indicate that an exception was thrown.</li> |
| |
| <li>This is finally passed to |
| <code>ExitUtil.terminate(ExitUtil.ExitException)</code>, |
| by way of |
| <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLauncher.html#exit-org.apache.hadoop.util.ExitUtil.ExitException-"><code>ServiceLauncher.exit(ExitUtil.ExitException)</code></a>; |
| a method designed to allow subclasses to override for testing.</li> |
| |
| <li>The <code>ExitUtil</code> class then terminates the JVM |
| with the specified exit code, printing the <code>toString()</code> value |
| of the exception if the return code is non-zero.</li> |
| </ol> |
| |
| This process may seem convoluted, but it is designed to allow any exception |
| in the Hadoop exception hierarchy to generate exit codes, |
| and to minimize the amount of exception wrapping which takes place. |
| |
| <h2>Interrupt Handling</h2> |
| |
| The Service Launcher has a helper class, |
| <code>InterruptEscalator</code> |
| to handle the standard SIGKILL signal and control-C signals. |
| This class registers for signal callbacks from these signals, and, |
| when received, attempts to stop the service in a limited period of time. |
| It then triggers a JVM shutdown by way of |
| <code>ExitUtil.terminate(int, String)</code> |
| <p> |
| If a second signal is received, the |
| <code>InterruptEscalator</code> |
| reacts by triggering an immediate JVM halt, invoking |
| <code>ExitUtil.halt(int, String)</code>. |
| This escalation process is designed to address the situation in which |
| a shutdown-hook can block, yet the caller (such as an init.d daemon) |
| wishes to kill the process. |
| The shutdown script should repeat the kill signal after a chosen time period, |
| to trigger the more aggressive process halt. The exit code will always be |
| <a href="../../../../../org/apache/hadoop/service/launcher/LauncherExitCodes.html#EXIT_INTERRUPTED"><code>LauncherExitCodes.EXIT_INTERRUPTED</code></a>. |
| <p> |
| The <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLauncher.html" title="class in org.apache.hadoop.service.launcher"><code>ServiceLauncher</code></a> also registers |
| a <code>ServiceShutdownHook</code> with the |
| Hadoop shutdown hook manager, unregistering it afterwards. This hook will |
| stop the service if a shutdown request is received, so ensuring that |
| if the JVM is exited by any thread, an attempt to shut down the service |
| will be made. |
| |
| |
| <h2>Configuration class creation</h2> |
| |
| The Configuration class used to initialize a service is a basic |
| <a href="../../../../../org/apache/hadoop/conf/Configuration.html" title="class in org.apache.hadoop.conf"><code>Configuration</code></a> instance. As the launcher is |
| the entry point for an application, this implies that the HDFS, YARN or other |
| default configurations will not have been forced in through the constructors |
| of <code>HdfsConfiguration</code> or <code>YarnConfiguration</code>. |
| <p> |
| What the launcher does do is use reflection to try and create instances of |
| these classes simply to force in the common resources. If the classes are |
| not on the classpath this fact will be logged. |
| <p> |
| Applications may consider it essential to either force load in the relevant |
| configuration, or pass it down to the service being created. In which |
| case further measures may be needed. |
| |
| <p><b>1: Creation in an extended <code>ServiceLauncher</code></b> |
| |
| <p> |
| Subclass the Service launcher and override its |
| <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLauncher.html#createConfiguration--"><code>ServiceLauncher.createConfiguration()</code></a> |
| method with one that creates the right configuration. |
| This is good if a single |
| launcher can be created for all services launched by a module, such as |
| HDFS or YARN. It does imply a dedicated script to invoke the custom |
| <code>main()</code> method. |
| |
| <p><b>2: Creation in <code>bindArgs()</code></b> |
| |
| <p> |
| In |
| <a href="../../../../../org/apache/hadoop/service/launcher/LaunchableService.html#bindArgs-org.apache.hadoop.conf.Configuration-java.util.List-"><code>LaunchableService.bindArgs(Configuration, List)</code></a>, |
| a new configuration is created: |
| |
| <pre> |
| public Configuration bindArgs(Configuration config, List<String> args) |
| throws Exception { |
| Configuration newConf = new YarnConfiguration(config); |
| return newConf; |
| } |
| </pre> |
| |
| This guarantees a configuration of the right type is generated for all |
| instances created via the service launcher. It does imply that this is |
| expected to be only way that services will be launched. |
| |
| <p><b>3: Creation in <code>serviceInit()</code></b> |
| |
| <pre> |
| protected void serviceInit(Configuration conf) throws Exception { |
| super.serviceInit(new YarnConfiguration(conf)); |
| } |
| </pre> |
| |
| <p> |
| This is a strategy used by many existing YARN services, and is ideal for |
| services which do not implement the LaunchableService interface. Its one |
| weakness is that the configuration is now private to that instance. Some |
| YARN services use a single shared configuration instance as a way of |
| propagating information between peer services in a |
| <a href="../../../../../org/apache/hadoop/service/CompositeService.html" title="class in org.apache.hadoop.service"><code>CompositeService</code></a>. |
| While a dangerous practice, it does happen. |
| |
| |
| <b>Summary</b>: the ServiceLauncher makes a best-effort attempt to load the |
| standard Configuration subclasses, but does not fail if they are not present. |
| Services which require a specific subclasses should follow one of the |
| strategies listed; |
| creation in <code>serviceInit()</code> is the recommended policy. |
| |
| <h2>Configuration file loading</h2> |
| |
| Before the service is bound to the CLI, the ServiceLauncher scans through |
| all the arguments after the first one, looking for instances of the argument |
| <a href="../../../../../org/apache/hadoop/service/launcher/LauncherArguments.html#ARG_CONF"><code>LauncherArguments.ARG_CONF</code></a> |
| argument pair: <code>--conf &lt;file&gt;</code>. This must refer to a file |
| in the local filesystem which exists. |
| <p> |
| It will be loaded into the Hadoop configuration |
| class (the one created by the |
| <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLauncher.html#createConfiguration--"><code>ServiceLauncher.createConfiguration()</code></a> |
| method. |
| If this argument is repeated multiple times, all configuration |
| files are merged with the latest file on the command line being the |
| last one to be applied. |
| <p> |
| All the <code>--conf &lt;file&gt;</code> argument pairs are stripped off |
| the argument list provided to the instantiated service; they get the |
| merged configuration, but not the commands used to create it. |
| |
| <h2>Utility Classes</h2> |
| |
| <ul> |
| |
| <li> |
| <code>IrqHandler</code>: registers interrupt |
| handlers using <code>sun.misc</code> APIs. |
| </li> |
| |
| <li> |
| <a href="../../../../../org/apache/hadoop/service/launcher/ServiceLaunchException.html" title="class in org.apache.hadoop.service.launcher"><code>ServiceLaunchException</code></a>: a |
| subclass of <a href="../../../../../org/apache/hadoop/util/ExitUtil.ExitException.html" title="class in org.apache.hadoop.util"><code>ExitUtil.ExitException</code></a> which |
| takes a String-formatted format string and a list of arguments to create |
| the exception text. |
| </li> |
| |
| </ul></div> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-use.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../../org/apache/hadoop/service/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../../org/apache/hadoop/tools/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../../index.html?org/apache/hadoop/service/launcher/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| <p class="legalCopy"><small>Copyright © 2008–2021 <a href="https://www.apache.org">Apache Software Foundation</a>. All rights reserved.</small></p> |
| </body> |
| </html> |
