<!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_362) on Mon Mar 06 12:18:46 UTC 2023 -->
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>org.apache.hadoop.service.launcher (Apache Hadoop Main 3.4.0-SNAPSHOT API)</title>
<meta name="date" content="2023-03-06">
<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 Main 3.4.0-SNAPSHOT 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&nbsp;Package</a></li>
<li><a href="../../../../../org/apache/hadoop/streaming/package-summary.html">Next&nbsp;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&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../../allclasses-noframe.html">All&nbsp;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&nbsp;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:&nbsp;<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">&nbsp;</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/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="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">&nbsp;</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>
</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">&nbsp;</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 <code>ServiceLauncher</code> 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 
 <code>ServiceLauncher.main(String[])</code>
 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 &mdash;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 &mdash;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 &mdash;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>

 To view the workflow in sequence, it is:
 <ol>
 <li>(prepare configuration files &mdash;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
 <code>ExitCodeProvider</code>
 interface is considered be a provider of the exit code: the method
 <code>ExitCodeProvider.getExitCode()</code>
 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
 <code>ExitUtil.ExitException</code>
 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 <code>ExitUtil.ExitException</code>.

 <p>
 If the exception is already an instance or subclass of 
 <code>ExitUtil.ExitException</code>, 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 <code>ServiceLauncher</code>
 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 <code>ExitUtil.ExitException</code> itself
 implements <code>ExitCodeProvider.getExitCode()</code>

 </p>
 If an exception does not implement
 <code>ExitCodeProvider.getExitCode()</code>,
 it will be wrapped in an <code>ExitUtil.ExitException</code>
 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 <code>ExitCodeProvider</code>,
 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
 <code>ServiceLauncher.exit(ExitUtil.ExitException)</code>;
 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>

 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 <code>ServiceLauncher</code> 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.
 </p>

 <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.
 
 <b>1: Creation in an extended <code>ServiceLauncher</code></b>
 
 <p>
 Subclass the Service launcher and override its
 <code>ServiceLauncher.createConfiguration()</code>
 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.

 <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&lt;String&gt; 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></p>

 <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.
 </p>

 <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
 <code>LauncherArguments.ARG_CONF</code>
 argument pair: <code>--conf &amp;lt;file&amp;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
 <code>ServiceLauncher.createConfiguration()</code>
 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 &amp;lt;file&amp;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 <code>ExitUtil.ExitException</code> 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&nbsp;Package</a></li>
<li><a href="../../../../../org/apache/hadoop/streaming/package-summary.html">Next&nbsp;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&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../../allclasses-noframe.html">All&nbsp;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 &#169; 2023 <a href="https://www.apache.org">Apache Software Foundation</a>. All rights reserved.</small></p>
</body>
</html>