/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.microservice;

import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.FileUtils.*;
import static org.apache.juneau.commons.utils.IoUtils.*;
import static org.apache.juneau.commons.utils.ObjectUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;

import java.io.*;
import java.nio.file.*;
import java.text.*;
import java.util.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.*;
import java.util.jar.*;
import java.util.logging.*;

import org.apache.juneau.commons.inject.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.commons.runtime.*;
import org.apache.juneau.commons.settings.*;
import org.apache.juneau.commons.svl.*;
import org.apache.juneau.commons.svl.vars.*;
import org.apache.juneau.config.*;
import org.apache.juneau.config.event.*;
import org.apache.juneau.config.store.*;
import org.apache.juneau.config.store.FileStore;
import org.apache.juneau.config.vars.*;
import org.apache.juneau.marshall.collections.*;
import org.apache.juneau.marshall.cp.*;
import org.apache.juneau.marshall.parser.ParseException;
import org.apache.juneau.microservice.console.*;
import org.apache.juneau.microservice.logging.*;

/**
 * Parent class for all microservices.
 *
 * <p>
 * A microservice defines a simple API for starting and stopping simple Java services contained in executable jars.
 *
 * <p>
 * The general command for creating and starting a microservice from a main method is as follows:
 * <p class='bjava'>
 *    <jk>public static void</jk> main(String[] <jv>args</jv>) {
 *       Microservice.<jsm>create</jsm>().args(<jv>args</jv>).build().start().join();
 *  }
 * </p>
 *
 * <p>
 * Your microservice class must be specified as the <jk>Main-Class</jk> entry in the manifest file of your microservice
 * jar file if it's an executable jar.
 *
 * <h5 class='topic'>Microservice Configuration</h5>
 *
 * This class defines the following method for accessing configuration for your microservice:
 * <ul class='spaced-list'>
 *    <li>
 *       {@link #getArgs()} - The command-line arguments passed to the jar file.
 *    <li>
 *       {@link #getConfig()} - An external INI-style configuration file.
 *    <li>
 *       {@link #getManifest()} - The manifest file for the main jar file.
 * </ul>
 *
 * <h5 class='topic'>Lifecycle Methods</h5>
 *
 * Subclasses must implement the following lifecycle methods:
 * <ul class='spaced-list'>
 *    <li>
 *       {@link #init()} - Gets executed immediately following construction.
 *    <li>
 *       {@link #start()} - Gets executed during startup.
 *    <li>
 *       {@link #stop()} - Gets executed when 'exit' is typed in the console or an external shutdown signal is received.
 *    <li>
 *       {@link #kill()} - Can be used to forcibly shut down the service.  Doesn't get called during normal operation.
 * </ul>
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauMicroservice">juneau-microservice</a>
 * </ul>
 */
@SuppressWarnings({
   "java:S112", // throws Exception intentional - callback/lifecycle method
   "java:S3740", // Raw Class/Builder types used intentionally for reflective microservice wiring where type parameters are not available
   "resource", // consoleReader and consoleWriter are backed by system streams or caller-provided streams; lifecycle managed by stop()
   "unchecked" // Type erasure requires unchecked cast for varargs
})
public class Microservice implements ConfigEventListener {

   /**
    * Builder class.
    */
   public static class Builder implements BeanStoreOverridable<Builder> {

      Args args;
      ManifestFile manifest;
      Logger logger;
      LogConfig logConfig;
      Config config;
      String configName;
      ConfigStore configStore;
      Config.Builder configBuilder = Config.create();
      Boolean consoleEnabled;
      List<ConsoleCommand> consoleCommands = list();
      VarResolver.Builder varResolver = VarResolver.create().defaultVars().vars(ConfigVar.class);
      Scanner consoleReader;
      PrintWriter consoleWriter;
      MicroserviceListener listener;
      File workingDir;
      WritableBeanStore beanStore;
      BeanStore overridingBeanStore;
      List<Class<?>> configurations = list();

      /**
       * Constructor.
       */
      protected Builder() {}

      /**
       * {@link Inject @Inject}-annotated initializer that populates {@link #workingDir} from the
       * {@code juneau.workingDir} property (system property &rarr; environment variable &rarr;
       * registered property sources) when the property is set. Has no effect if {@code workingDir}
       * was already set programmatically.
       *
       * @param workingDirEnv The resolved {@code juneau.workingDir} value, or {@code null}/empty
       *    when not configured.
       */
      @Inject
      public void initWorkingDirFromEnv(@Value("${juneau.workingDir}") String workingDirEnv) {
         if (workingDir == null && ine(workingDirEnv))
            workingDir = new File(workingDirEnv);
      }

      /**
       * Copy constructor.
       *
       * @param copyFrom The builder to copy.
       */
      protected Builder(Builder copyFrom) {
         this.args = copyFrom.args;
         this.manifest = copyFrom.manifest;
         this.logger = copyFrom.logger;
         this.config = copyFrom.config;
         this.configName = copyFrom.configName;
         this.configStore = copyFrom.configStore;
         this.listener = copyFrom.listener;
         this.consoleCommands = new ArrayList<>(copyFrom.consoleCommands);
         this.logConfig = LogConfig.copyOrNull(copyFrom.logConfig);
         this.consoleEnabled = copyFrom.consoleEnabled;
         this.configBuilder = copyFrom.configBuilder;
         this.varResolver = copyFrom.varResolver;
         this.consoleReader = copyFrom.consoleReader;
         this.consoleWriter = copyFrom.consoleWriter;
         this.workingDir = copyFrom.workingDir;
         this.beanStore = copyFrom.beanStore;
         this.overridingBeanStore = copyFrom.overridingBeanStore;
         this.configurations = new ArrayList<>(copyFrom.configurations);
      }

      /**
       * Specifies the command-line arguments passed into the Java command.
       *
       * <p>
       * This is required if you use {@link Microservice#getArgs()} or <c>$A</c> string variables.
       *
       * @param args
       *    The command-line arguments passed into the Java command as a pre-parsed {@link Args} object.
       *    <br>Can be <jk>null</jk> (an empty {@link Args} is used).
       * @return This object.
       */
      public Builder args(Args args) {
         this.args = args;
         return this;
      }

      /**
       * Specifies the command-line arguments passed into the Java command.
       *
       * <p>
       * This is required if you use {@link Microservice#getArgs()} or <c>$A</c> string variables.
       *
       * @param args
       *    The command-line arguments passed into the Java command as the raw command-line arguments.
       * @return This object.
       */
      public Builder args(String...args) {
         this.args = new Args(args);
         return this;
      }

      /**
       * Instantiate a new microservice using the settings defined on this builder.
       *
       * @return A new microservice.
       * @throws Exception Error occurred.
       */
      public Microservice build() throws Exception {
         return new Microservice(this);
      }

      /**
       * Specifies the config for initializing this microservice.
       *
       * <p>
       * Calling this method overrides the default configuration controlled by the {@link #configName(String)} and {@link #configStore(ConfigStore)} methods.
       *
       * @param config The configuration.  Can be <jk>null</jk> (the configuration is auto-resolved).
       * @return This object.
       */
      public Builder config(Config config) {
         this.config = config;
         return this;
      }

      /**
       * Specifies the config name for initializing this microservice.
       *
       * <p>
       * If you do not specify the config file location, we attempt to resolve it through the following methods:
       * <ol class='spaced-list'>
       *    <li>
       *       Resolve file first in working directory, then in classpath, using the following names:
       *       <ul>
       *          <li>
       *             The <js>"configFile"</js> argument in the command line arguments passed in through the constructor.
       *          <li>
       *             The value of the <c>Main-Config</c> entry in the manifest file.
       *          <li>
       *             A config file in the same location and with the same name as the executable jar file.
       *             (e.g. <js>"java -jar myjar.jar"</js> will look for <js>"myjar.cfg"</js>).
       *       </ul>
       *    <li>
       *       Resolve any <js>"*.cfg"</js> file that can be found in the working directory.
       *    <li>
       *       Resolve any of the following files in the classpath:  <js>"juneau.cfg"</js>, <js>"system.cfg"</js>
       * </ol>
       *
       * <p>
       * If no configuration file is found, and empty in-memory configuration is used.
       *
       * @param configName The configuration name.  Can be <jk>null</jk> (the configuration name is auto-resolved).
       * @return This object.
       */
      public Builder configName(String configName) {
         this.configName = configName;
         return this;
      }

      /**
       * Specifies the config store to use for storing and retrieving configurations.
       *
       * <p>
       * By default, we use a {@link FileStore} store for configuration files.
       *
       * @param configStore The configuration store.  Can be <jk>null</jk> (a default {@link FileStore} is used).
       * @return This object.
       */
      public Builder configStore(ConfigStore configStore) {
         this.configStore = configStore;
         return this;
      }

      /**
       * Specifies the console input and output.
       *
       * <p>
       * If not specified, uses the console returned by {@link System#console()}.
       * If that is not available, uses {@link System#in} and {@link System#out}.
       *
       * <p>
       * Note that these are ignored if the console is not enabled via {@link #consoleEnabled(boolean)}.
       *
       * @param consoleReader The console input.  Can be <jk>null</jk> (the default console input is used).
       * @param consoleWriter The console output.  Can be <jk>null</jk> (the default console output is used).
       * @return This object.
       */
      public Builder console(Scanner consoleReader, PrintWriter consoleWriter) {
         this.consoleReader = consoleReader;
         this.consoleWriter = consoleWriter;
         return this;
      }

      /**
       * Specifies console commands to make available on the Java console.
       *
       * <p>
       * Note that these are ignored if the console is not enabled via {@link #consoleEnabled(boolean)}.
       *
       * <p>
       * This list augments the commands defined via the <js>"Console/commands"</js> configuration setting.
       *
       * <p>
       * This method can only be used on console commands with no-arg constructors.
       *
       * @param consoleCommands The list of console commands to append to the list of available commands.
       * @return This object.
       * @throws ExecutableException Exception occurred on invoked constructor/method/field.
       */
      public Builder consoleCommands(Class<? extends ConsoleCommand>...consoleCommands) throws ExecutableException {
         try {
            for (var cc : consoleCommands)
               this.consoleCommands.add(cc.getDeclaredConstructor().newInstance());
         } catch (Exception e) {
            throw new ExecutableException(e);
         }
         return this;
      }

      /**
       * Specifies console commands to make available on the Java console.
       *
       * <p>
       * Note that these are ignored if the console is not enabled via {@link #consoleEnabled(boolean)}.
       *
       * <p>
       * This list augments the commands defined via the <js>"Console/commands"</js> configuration setting.
       *
       * @param consoleCommands The list of console commands to append to the list of available commands.
       * @return This object.
       */
      public Builder consoleCommands(ConsoleCommand...consoleCommands) {
         addAll(this.consoleCommands, consoleCommands);
         return this;
      }

      /**
       * Specifies that the Java console is enabled for this microservice.
       *
       * <p>
       * If not specified, this value is taken from the <js>"Console/enabled"</js> configuration setting.
       * If not specified in the configuration, defaults to <jk>false</jk>.
       *
       * @param consoleEnabled <jk>true</jk> if the Java console is enabled for this microservice.
       * @return This object.
       */
      public Builder consoleEnabled(boolean consoleEnabled) {
         this.consoleEnabled = consoleEnabled;
         return this;
      }

      /**
       * Creates a copy of this builder.
       *
       * @return A new copy of this builder.
       */
      public Builder copy() {
         return new Builder(this);
      }

      /**
       * Registers an event listener for this microservice.
       *
       * @param listener An event listener for this microservice.  Can be <jk>null</jk> (no listener is registered).
       * @return This object.
       */
      public Builder listener(MicroserviceListener listener) {
         this.listener = listener;
         return this;
      }

      /**
       * Specifies logging instructions for the microservice.
       *
       * <p>
       * If not specified, the values are taken from the <js>"Logging"</js> section of the configuration.
       *
       * <p>
       * This method is ignored if {@link #logger(Logger)} is used to set the microservice logger.
       *
       * @param logConfig The log configuration.  Can be <jk>null</jk> (a default {@link LogConfig} is used).
       * @return This object.
       */
      public Builder logConfig(LogConfig logConfig) {
         this.logConfig = logConfig;
         return this;
      }

      /**
       * Specifies the logger used by the microservice and returned by the {@link Microservice#getLogger()} method.
       *
       * <p>
       * Calling this method overrides the default logging mechanism controlled by the {@link #logConfig(LogConfig)} method.
       *
       * @param logger The logger to use for logging microservice messages.  Can be <jk>null</jk> (a default logger is created).
       * @return This object.
       */
      public Builder logger(Logger logger) {
         this.logger = logger;
         return this;
      }

      /**
       * Specifies the manifest file of the jar file this microservice is contained within.
       *
       * <p>
       * This is required if you use {@link Microservice#getManifest()}.
       * It's also used to locate initialization values such as <c>Main-Config</c>.
       *
       * <p>
       * If you do not specify the manifest file, we attempt to resolve it through the following methods:
       * <ol class='spaced-list'>
       *    <li>
       *       Looking on the file system for a file at <js>"META-INF/MANIFEST.MF"</js>.
       *       This is primarily to allow for running microservices from within eclipse workspaces where the manifest file
       *       is located in the project root.
       *    <li>
       *       Using the class loader for this class to find the file at the URL <js>"META-INF/MANIFEST.MF"</js>.
       * </ol>
       *
       * @param value
       *    The manifest file of this microservice.
       *    <br>Can be any of the following types:
       *    <ul>
       *       <li>{@link ManifestFile}
       *       <li>{@link Manifest}
       *       <li>{@link Reader} - Containing the raw contents of the manifest.  Note that the input must end with a newline.
       *       <li>{@link InputStream} - Containing the raw contents of the manifest.  Note that the input must end with a newline.
       *       <li>{@link File} - File containing the raw contents of the manifest.
       *       <li>{@link String} - Path to file containing the raw contents of the manifest.
       *       <li>{@link Class} - Finds and loads the manifest file of the jar file that the specified class is contained within.
       *    </ul>
       *    <br>Can be <jk>null</jk> (the manifest is auto-resolved).
       * @return This object.
       * @throws IOException Thrown by underlying stream.
       */
      public Builder manifest(Object value) throws IOException {
         if (value == null)
            this.manifest = null;
         else if (value instanceof ManifestFile value2)
            this.manifest = value2;
         else if (value instanceof Manifest value2)
            this.manifest = new ManifestFile(value2);
         else if (value instanceof Reader value2)
            this.manifest = new ManifestFile(value2);
         else if (value instanceof InputStream value2)
            this.manifest = new ManifestFile(value2);
         else if (value instanceof File value2)
            this.manifest = new ManifestFile(value2);
         else if (value instanceof Path value2)
            this.manifest = new ManifestFile(value2);
         else if (value instanceof String value2)
            this.manifest = new ManifestFile(resolveFile(value2));
         else if (value instanceof Class value2)
            this.manifest = new ManifestFile(value2);
         else
            throw rex("Invalid type passed to Builder.manifest(Object).  Type=[%s]", cn(value));

         return this;
      }

      /**
       * Adds a bean for vars defined in the var resolver.
       *
       * <p>
       * This calls {@link org.apache.juneau.commons.svl.VarResolver.Builder#bean(Class,Object) VarResolver.Builder#bean(Class,Object)} on the var resolver used to construct the configuration
       * object returned by {@link Microservice#getConfig()} and the var resolver returned by {@link Microservice#getVarResolver()}.
       *
       * @param c The bean type.
       * @param value The bean.
       * @param <T> The bean type.
       * @return This object.
       */
      public <T> Builder varBean(Class<T> c, T value) {
         varResolver.bean(c, value);
         return this;
      }

      /**
       * Augments the set of variables defined in the configuration and var resolver.
       *
       * <p>
       * This calls {@link org.apache.juneau.commons.svl.VarResolver.Builder#vars(Class[]) VarResolver.Builder#vars(Class[])} on the var resolver used to construct the configuration
       * object returned by {@link Microservice#getConfig()} and the var resolver returned by {@link Microservice#getVarResolver()}.
       *
       * @param vars The set of variables to append to the var resolver builder.
       * @return This object.
       */
      public Builder vars(Class<? extends Var>...vars) {
         varResolver.vars(vars);
         return this;
      }

      /**
       * Specifies the directory to use to resolve the config file and other paths defined with the config file.
       *
       * @param workingDir The working directory, or <jk>null</jk> to use the underlying working directory.
       * @return This object.
       */
      public Builder workingDir(File workingDir) {
         this.workingDir = workingDir;
         return this;
      }

      /**
       * Specifies the directory to use to resolve the config file and other paths defined with the config file.
       *
       * @param workingDir The working directory.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder workingDir(String workingDir) {
         this.workingDir = new File(workingDir);
         return this;
      }

      /**
       * Registers one or more <c>@Configuration</c>-annotated classes whose <c>@Bean</c> methods/fields
       * will be processed during microservice bootstrap.
       *
       * <p>
       * Beans contributed by <c>@Configuration</c> classes are stored in the microservice's internal
       * {@link WritableBeanStore} (accessible via {@link Microservice#getBeanStore()}).  They become
       * available to other <c>@Bean</c> factory methods via constructor injection.
       *
       * <p>
       * Explicit builder calls (e.g. {@link #config(Config)}, {@link #args(Args)}) take precedence over
       * <c>@Bean</c>-supplied values — the resolved field is registered into the bean store <i>after</i>
       * configurations are processed, overwriting any same-type <c>@Bean</c> contribution.
       *
       * @param configurations The configuration classes.  Can be <jk>null</jk> or empty (no-op); <jk>null</jk> elements are ignored.
       * @return This object.
       * @since 10.0.0
       */
      public Builder configurations(Class<?>... configurations) {
         addAllNn(this.configurations, configurations);
         return this;
      }

      /**
       * Registers one or more <c>@Configuration</c>-annotated classes.
       *
       * @param configurations The configuration classes.  Can be <jk>null</jk> or empty (no-op); <jk>null</jk> elements are ignored.
       * @return This object.
       * @see #configurations(Class...)
       * @since 10.0.0
       */
      public Builder configurations(List<Class<?>> configurations) {
         addAllNn(this.configurations, configurations);
         return this;
      }

      /**
       * Specifies an external {@link WritableBeanStore} to use instead of constructing a fresh one.
       *
       * <p>
       * Useful for testing and for composing a microservice into a larger application that already owns
       * a bean store (e.g. a Spring-backed parent store).  When set, configurations supplied via
       * {@link #configurations(Class...)} are registered into this store, and the microservice's
       * resolved values (args, manifest, config, var resolver, listener, microservice itself) are also
       * registered into it.
       *
       * @param beanStore The external bean store.  Can be <jk>null</jk> to use a fresh internal store.
       * @return This object.
       * @since 10.0.0
       */
      public Builder beanStore(WritableBeanStore beanStore) {
         this.beanStore = beanStore;
         return this;
      }

      /**
       * Installs the supplied {@link BeanStore} as the {@code overridingParent} of this microservice's
       * bean store.
       *
       * <p>
       * The overlay is consulted <i>before</i> any locally-registered beans during construction-time
       * reflective injection (see {@link BasicBeanStore#BasicBeanStore(BeanStore, BeanStore)}), so
       * test-time overrides win over the microservice's own {@code @Bean} factory contributions.  This
       * is the <b>Mode INJECT</b> wiring pattern for {@code Microservice}-based tests &mdash; the overlay is
       * installed before the microservice is constructed and lives for the microservice's full lifetime.
       * For per-test push/pop overlays against an already-started microservice, see
       * {@link Microservice#getBeanStore()} and the push/pop primitives on
       * {@link WritableBeanStore}.
       *
       * <p>
       * Composes with {@link #beanStore(WritableBeanStore)}: when both are supplied, the supplied
       * external store becomes the regular parent and the overlay becomes the overriding parent of
       * a fresh wrapping {@link BasicBeanStore}.
       *
       * @param store The override layer.  Can be <jk>null</jk> to clear a previously-set value.
       * @return This object.
       * @since 10.0.0
       */
      @Override
      public Builder overridingBeanStore(BeanStore store) {
         this.overridingBeanStore = store;
         return this;
      }

      /**
       * Resolves the specified path.
       *
       * <p>
       * If the working directory has been explicitly specified, relative paths are resolved relative to that.
       *
       * @param path The path to resolve.  Must not be <jk>null</jk>.
       * @return The resolved file.
       */
      protected File resolveFile(String path) {
         if (Paths.get(path).isAbsolute())
            return new File(path);
         if (nn(workingDir))
            return new File(workingDir, path);
         return new File(path);
      }
   }

   private static final AtomicReference<Microservice> instance = new AtomicReference<>();

   /**
    * Creates a new builder for this object.
    *
    * <p>
    * Routes builder construction through {@link BeanInstantiator} so that the
    * {@code juneau.workingDir} env default is resolved through the active
    * {@link Settings Settings} chain.
    *
    * @return A new microservice builder.
    */
   public static Builder create() {
      return create(BasicBeanStore.INSTANCE);
   }

   /**
    * Creates a new builder for this object using the supplied {@link BeanStore} for
    * {@link Value @Value}-resolution and dependency injection.
    *
    * @param beanStore The bean store to use for dependency injection.
    * @return A new microservice builder.
    */
   public static Builder create(BeanStore beanStore) {
      return BeanInstantiator.of(Builder.class, beanStore).run();
   }

   /**
    * Returns the Microservice instance.
    *
    * <p>
    * This method only works if there's only one Microservice instance in a JVM.
    * Otherwise, it's just overwritten by the last instantiated microservice.
    *
    * @return The Microservice instance, or <jk>null</jk> if there isn't one.
    */
   public static Microservice getInstance() {
      return instance.get();
   }

   private static void setInstance(Microservice m) {
      instance.set(m);
   }

   final Messages messages = Messages.of(Microservice.class);

   private final Builder builder;
   private final Args args;
   private final Config config;
   private final ManifestFile manifest;
   private final VarResolver varResolver;
   private final Map<String,ConsoleCommand> consoleCommandMap = new ConcurrentHashMap<>();
   private final boolean consoleEnabled;
   private final Scanner consoleReader;
   private final PrintWriter consoleWriter;
   private final Thread consoleThread;
   final File workingDir;
   private final String configName;
   private final WritableBeanStore beanStore;
   private volatile boolean stopped;
   private final ConfigPropertySource settingsSource;

   private final AtomicReference<Logger> logger = new AtomicReference<>();

   /**
    * Constructor.
    *
    * @param builder The builder containing the settings for this microservice.
    * @throws IOException Problem occurred reading file.
    * @throws ParseException Malformed input encountered.
    */
   @SuppressWarnings({
      "java:S3776" // Cognitive complexity acceptable for microservice initialization
   })
   protected Microservice(Builder builder) throws IOException, ParseException {
      setInstance(this);
      this.builder = builder.copy();
      this.workingDir = builder.workingDir;
      this.configName = builder.configName;

      // --------------------------------------------------------------------------------
      // Initialize the bean store and register any @Configuration classes.
      // @Bean-supplied values become candidate inputs for field resolution below.
      // Explicit builder calls always win and overwrite @Bean contributions afterward.
      //
      // Composition with the overriding bean store (test-time overlay):
      //   - no external store and no overlay: a fresh empty bean store is created.
      //   - no external store but an overlay: a fresh bean store is created with the overlay as its overriding parent.
      //   - an external store and no overlay: the external store is used as-is.
      //   - an external store and an overlay: the external store is wrapped in a bean store with the overlay as its overriding parent.
      // --------------------------------------------------------------------------------
      if (nn(builder.overridingBeanStore)) {
         this.beanStore = new BasicBeanStore(builder.beanStore, builder.overridingBeanStore);
      } else {
         this.beanStore = nn(builder.beanStore) ? builder.beanStore : new BasicBeanStore();
      }
      if (! builder.configurations.isEmpty())
         beanStore.registerConfigurations(builder.configurations.toArray(new Class<?>[0]));

      // Resolve Args: builder > @Bean > empty.
      this.args = nn(builder.args)
         ? builder.args
         : beanStore.getBean(Args.class).orElseGet(() -> new Args(new String[0]));
      beanStore.addBean(Args.class, this.args);

      // --------------------------------------------------------------------------------
      // Try to get the manifest file if it wasn't already set.
      // --------------------------------------------------------------------------------
      var manifest2 = builder.manifest;
      if (manifest2 == null)
         manifest2 = beanStore.getBean(ManifestFile.class).orElse(null);
      if (manifest2 == null) {
         var m = new Manifest();

         // If running within an eclipse workspace, need to get it from the file system.
         var f = resolveFile("META-INF/MANIFEST.MF");
         if (f.exists() && f.canRead()) {
            try (var fis = new FileInputStream(f)) {
               m.read(fis);
            } catch (IOException e) {
               throw ioex(e, "Problem detected in MANIFEST.MF.  Contents below:\n%s", read(f), e);
            }
         } else {
            // Otherwise, read from manifest file in the jar file containing the main class.
            var url = getClass().getResource("META-INF/MANIFEST.MF");
            if (nn(url)) {
               try {
                  m.read(url.openStream());
               } catch (IOException e) {
                  throw ioex(e, "Problem detected in MANIFEST.MF.  Contents below:\n%s", read(url.openStream()), e);
               }
            }
         }
         manifest2 = new ManifestFile(m);
      }
      this.manifest = manifest2;
      beanStore.addBean(ManifestFile.class, this.manifest);
      builder.varResolver
         .vars(ArgsVar.create(() -> this.args))
         .vars(ManifestFileVar.create(() -> this.manifest));

      // --------------------------------------------------------------------------------
      // Try to resolve the configuration if not specified.
      // --------------------------------------------------------------------------------
      var config2 = nn(builder.config) ? builder.config : beanStore.getBean(Config.class).orElse(null);
      var configBuilder = builder.configBuilder.varResolver(builder.varResolver.build()).store(MemoryStore.DEFAULT);
      if (config2 == null) {
         var store = builder.configStore;
         var cfs = workingDir == null ? FileStore.DEFAULT : FileStore.create().directory(workingDir).build();
         boolean found = false;
         for (var name : getCandidateConfigNames()) {
            if (found)
               break;
            if (nn(store)) {
               if (store.exists(name)) {
                  configBuilder.store(store).name(name);
                  found = true;
               }
            } else {
               if (cfs.exists(name)) {
                  configBuilder.store(cfs).name(name);
                  found = true;
               } else if (ClasspathStore.DEFAULT.exists(name)) {
                  configBuilder.store(ClasspathStore.DEFAULT).name(name);
                  found = true;
               }
            }
         }
         config2 = configBuilder.build();
      }
      this.config = config2;
      Config.setSystemDefault(this.config);
      this.config.addListener(this);
      this.settingsSource = new ConfigPropertySource(this.config);
      Settings.get().addSource(this.settingsSource);
      beanStore.addBean(Config.class, this.config);
      this.varResolver = builder.varResolver.bean(Config.class, config2).build();
      beanStore.addBean(VarResolver.class, this.varResolver);

      // --------------------------------------------------------------------------------
      // Initialize console commands.
      // --------------------------------------------------------------------------------
      this.consoleEnabled = coalesce(builder.consoleEnabled, config.get("Console/enabled").asBoolean().orElse(false));
      if (consoleEnabled) {
         var c = System.console();
         this.consoleReader = coalesce(builder.consoleReader, new Scanner(c == null ? new InputStreamReader(System.in) : c.reader()));
         this.consoleWriter = coalesce(builder.consoleWriter, c == null ? createLoggerConsoleWriter() : c.writer());

         // @Bean-supplied console commands (registered first, then overridable by builder/config below).
         for (var cc : beanStore.getBeansOfType(ConsoleCommand.class).values())
            consoleCommandMap.put(cc.getName(), cc);
         for (var cc : builder.consoleCommands) {
            consoleCommandMap.put(cc.getName(), cc);
         }
         for (var s : config.get("Console/commands").asStringArray().orElse(new String[0])) {
            try {
               var cc = (ConsoleCommand)Class.forName(s).getDeclaredConstructor().newInstance();
               consoleCommandMap.put(cc.getName(), cc);
            } catch (Exception e) {
               getConsoleWriter().println("Could not create console command '" + s + "', " + localizedMessage(e));
            }
         }
         consoleThread = new Thread("ConsoleThread") {
            @Override /* Overridden from Thread */
            public void run() {
               var in = getConsoleReader();
               var out = getConsoleWriter();

               out.println(messages.getString("ListOfAvailableCommands"));
               for (var cc : new TreeMap<>(getConsoleCommands()).values())
                  out.append("\t").append(cc.getName()).append(" -- ").append(cc.getInfo()).println();
               out.println();

               while (true) {
                  out.append("> ").flush();
                  // Guard against empty/closed stdin: hasNextLine() returns false at end-of-stream, so
                  // the loop ends gracefully instead of nextLine() throwing NoSuchElementException.
                  if (! in.hasNextLine())
                     break;
                  var line = in.nextLine();
                  var args2 = new Args(line);
                  if (! args2.isEmpty())
                     executeCommand(args2, in, out);
               }
            }
         };
         consoleThread.setDaemon(true);
      } else {
         this.consoleReader = null;
         this.consoleWriter = null;
         this.consoleThread = null;
      }
      // Resolve listeners.
      // If the builder supplies an explicit listener, register it under the unnamed key (overwriting any
      // same-key @Bean MicroserviceListener); it joins the fan-out alongside any other @Bean-supplied listeners.
      // If, after that, no MicroserviceListener exists in the store at all, register the default
      // BasicMicroserviceListener so the fan-out has at least one no-op participant.
      if (nn(builder.listener))
         beanStore.addBean(MicroserviceListener.class, builder.listener);
      if (beanStore.getBeansOfType(MicroserviceListener.class).isEmpty())
         beanStore.addBean(MicroserviceListener.class, new BasicMicroserviceListener());

      // Self-register so @Bean factory methods can take Microservice as a constructor/method param.
      beanStore.addBean(Microservice.class, this);

      init();
   }

   /**
    * Prints a localized message to STDERR.
    *
    * <p>
    * Ignored if <js>"Console/enabled"</js> is <jk>false</jk>.
    *
    * @param mb The message bundle containing the message.  Must not be <jk>null</jk>.
    * @param messageKey The message key.
    * @param args Optional {@link MessageFormat}-style arguments.
    */
   public void err(Messages mb, String messageKey, Object...args) {
      var msg = mb.getString(messageKey, args);
      if (consoleEnabled)
         getLogger().warning(msg);  // NOT DEBUG
      log(Level.SEVERE, msg);
   }

   /**
    * Executes a console command.
    *
    * @param args
    *    The command arguments.  Must not be <jk>null</jk>.
    *    <br>The first entry in the arguments is always the command name.
    * @param in Console input.
    * @param out Console output.  Must not be <jk>null</jk>.
    * @return <jk>true</jk> if the command returned <jk>true</jk> meaning the console thread should exit.
    */
   public boolean executeCommand(Args args, Scanner in, PrintWriter out) {
      var cc = consoleCommandMap.get(args.get(0).orElse(null));
      if (cc == null) {
         out.println(messages.getString("UnknownCommand"));
      } else {
         try {
            return cc.execute(in, out, args);
         } catch (Exception e) {
            e.printStackTrace(out);
         }
      }
      return false;
   }

   /**
    * Convenience method for executing a console command directly.
    *
    * <p>
    * Allows you to execute a console command outside the console by simulating input and output.
    *
    * @param command The command name to execute.
    * @param input Optional input to the command.  Can be <jk>null</jk> (treated as an empty string).
    * @param args Optional command arguments to pass to the command.
    * @return The command output.
    */
   public String executeCommand(String command, String input, Object...args) {
      var sw = new StringWriter();
      var l = list();
      l.add(command);
      for (var a : args)
         l.add(s(a));
      var args2 = new Args(l.toArray(new String[l.size()]));
      try (var in = new Scanner(input == null ? "" : input); var out = new PrintWriter(sw)) {
         executeCommand(args2, in, out);
      }
      return sw.toString();
   }

   /**
    * Stops the console (if it's started) and calls {@link System#exit(int)}.
    *
    * @throws Exception Error occurred
    */
   public void exit() throws Exception {
      try {
         stopConsole();
      } catch (Exception e) {
         getLogger().log(Level.WARNING, "Error occurred while stopping the console.", e);
      }
      System.exit(0);
   }

   /**
    * Returns the command-line arguments passed into the application.
    *
    * <p>
    * This method can be called from the class constructor.
    *
    * <p>
    * See {@link Args} for details on using this method.
    *
    * @return The command-line arguments passed into the application.
    */
   public Args getArgs() { return args; }

   /**
    * Returns the external INI-style configuration file that can be used to configure your microservice.
    *
    * <p>
    * The config location is determined in the following order:
    * <ol class='spaced-list'>
    *    <li>
    *       The first argument passed to the microservice jar.
    *    <li>
    *       The <c>Main-Config</c> entry in the microservice jar manifest file.
    *    <li>
    *       The name of the microservice jar with a <js>".cfg"</js> suffix (e.g.
    *       <js>"mymicroservice.jar"</js>-&gt;<js>"mymicroservice.cfg"</js>).
    * </ol>
    *
    * <p>
    * If all methods for locating the config fail, then this method returns an empty config.
    *
    * <p>
    * Subclasses can set their own config file by using the following methods:
    * <ul class='javatree'>
    *    <li class='jm'>{@link Builder#configStore(ConfigStore)}
    *    <li class='jm'>{@link Builder#configName(String)}
    * </ul>
    *
    * <p>
    * String variables are automatically resolved using the variable resolver returned by {@link #getVarResolver()}.
    *
    * <p>
    * This method can be called from the class constructor.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bini'>
    *    <cc>#--------------------------</cc>
    *    <cc># My section</cc>
    *    <cc>#--------------------------</cc>
    *    <cs>[MySection]</cs>
    *
    *    <cc># An integer</cc>
    *    <ck>anInt</ck> = 1
    *
    *    <cc># A boolean</cc>
    *    <ck>aBoolean</ck> = true
    *
    *    <cc># An int array</cc>
    *    <ck>anIntArray</ck> = 1,2,3
    *
    *    <cc># A POJO that can be converted from a String</cc>
    *    <ck>aURL</ck> = http://foo
    *
    *    <cc># A POJO that can be converted from JSON</cc>
    *    <ck>aBean</ck> = {foo:'bar',baz:123}
    *
    *    <cc># A system property</cc>
    *    <ck>locale</ck> = $S{java.locale, en_US}
    *
    *    <cc># An environment variable</cc>
    *    <ck>path</ck> = $E{PATH, unknown}
    *
    *    <cc># A manifest file entry</cc>
    *    <ck>mainClass</ck> = $MF{Main-Class}
    *
    *    <cc># Another value in this config file</cc>
    *    <ck>sameAsAnInt</ck> = $C{MySection/anInt}
    *
    *    <cc># A command-line argument in the form "myarg=foo"</cc>
    *    <ck>myArg</ck> = $A{myarg}
    *
    *    <cc># The first command-line argument</cc>
    *    <ck>firstArg</ck> = $A{0}
    *
    *    <cc># Look for system property, or env var if that doesn't exist, or command-line arg if that doesn't exist.</cc>
    *    <ck>nested</ck> = $S{mySystemProperty,$E{MY_ENV_VAR,$A{0}}}
    *
    *    <cc># A POJO with embedded variables</cc>
    *    <ck>aBean2</ck> = {foo:'$A{0}',baz:$C{MySection/anInt}}
    * </p>
    *
    * <p class='bjava'>
    *    <jc>// Java code for accessing config entries above.</jc>
    *    Config <jv>config</jv> = getConfig();
    *
    *    <jk>int</jk> <jv>anInt</jv> = <jv>config</jv>.get(<js>"MySection/anInt"</js>).asInteger().orElse(-1);
    *    <jk>boolean</jk> <jv>aBoolean</jv> = <jv>config</jv>.get(<js>"MySection/aBoolean"</js>).asBoolean().orElse(<jk>false</jk>);
    *    <jk>int</jk>[] <jv>anIntArray</jv> = <jv>config</jv>.get(<js>"MySection/anIntArray"</js>).as(<jk>int</jk>[].<jk>class</jk>).orElse(<jk>null</jk>);
    *    URL <jv>aURL</jv> = <jv>config</jv>.get(<js>"MySection/aURL"</js>).as(URL.<jk>class</jk>).orElse(<jk>null</jk>);
    *    MyBean <jv>aBean</jv> = <jv>config</jv>.get(<js>"MySection/aBean"</js>).as(MyBean.<jk>class</jk>).orElse(<jk>null</jk>);
    *    Locale <jv>locale</jv> = <jv>config</jv>.get(<js>"MySection/locale"</js>).as(Locale.<jk>class</jk>).orElse(<jk>null</jk>);
    *    String <jv>path</jv> = <jv>config</jv>.get(<js>"MySection/path"</js>).orElse(<jk>null</jk>);
    *    String <jv>mainClass</jv> = <jv>config</jv>.get(<js>"MySection/mainClass"</js>).orElse(<jk>null</jk>);
    *    <jk>int</jk> <jv>sameAsAnInt</jv> = <jv>config</jv>.get(<js>"MySection/sameAsAnInt"</js>).asInteger().orElse(<jk>null</jk>);
    *    String <jv>myArg</jv> = <jv>config</jv>.getString(<js>"MySection/myArg"</js>);
    *    String <jv>firstArg</jv> = <jv>config</jv>.getString(<js>"MySection/firstArg"</js>);
    * </p>
    *
    * @return The config file for this application.  Never <jk>null</jk> (an empty config is returned if none is configured).
    */
   public Config getConfig() { return config; }

   /**
    * Returns the console commands associated with this microservice.
    *
    * @return The console commands associated with this microservice.  Never <jk>null</jk>.
    */
   public final Map<String,ConsoleCommand> getConsoleCommands() { return consoleCommandMap; }

   /**
    * Returns the logger for this microservice.
    *
    * @return The logger for this microservice.
    */
   public Logger getLogger() { return logger.get(); }

   /**
    * Returns the internal {@link WritableBeanStore} that backs this microservice's inject-aware bootstrap.
    *
    * <p>
    * The store is populated with this microservice's resolved values (<c>Args</c>, <c>ManifestFile</c>,
    * <c>Config</c>, <c>VarResolver</c>, <c>MicroserviceListener</c>, and <c>Microservice</c> itself),
    * plus any beans contributed by <c>@Configuration</c> classes registered via
    * {@link Builder#configurations(Class...)}.
    *
    * <p>
    * Lifecycle integration beans (e.g. <c>JettyServerComponent</c> contributed by <c>JettyConfiguration</c>)
    * implement {@link MicroserviceListener} and participate in the {@link #start()} / {@link #stop()}
    * fan-out.  External callers can query the store directly to look up beans contributed by user-supplied
    * <c>@Configuration</c> classes.
    *
    * <p>
    * The store is closed during {@link #stop()}, which triggers <c>@PreDestroy</c> hooks on resolved
    * beans.
    *
    * @return The microservice's bean store.  Never <jk>null</jk>.
    * @since 10.0.0
    */
   public WritableBeanStore getBeanStore() { return beanStore; }

   /**
    * Returns the main jar manifest file contents as a simple {@link JsonMap}.
    *
    * <p>
    * This map consists of the contents of {@link Manifest#getMainAttributes()} with the keys and entries converted to
    * simple strings.
    * <p>
    * This method can be called from the class constructor.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Get Main-Class from manifest file.</jc>
    *    String <jv>mainClass</jv> = Microservice.<jsm>getManifest</jsm>().getString(<js>"Main-Class"</js>, <js>"unknown"</js>);
    *
    *    <jc>// Get Rest-Resources from manifest file.</jc>
    *    String[] <jv>restResources</jv> = Microservice.<jsm>getManifest</jsm>().getStringArray(<js>"Rest-Resources"</js>);
    * </p>
    *
    * @return The manifest file from the main jar.  Never <jk>null</jk> (an empty manifest is returned if none could be retrieved).
    */
   public ManifestFile getManifest() { return manifest; }

   /**
    * Returns the variable resolver for resolving variables in strings and files.
    *
    * <p>
    * Variables can be controlled by the following methods:
    * <ul class='javatree'>
    *    <li class='jm'>{@link Builder#vars(Class...)}
    *    <li class='jm'>{@link Builder#varBean(Class,Object)}
    * </ul>
    *
    * @return The VarResolver used by this Microservice.  Never <jk>null</jk>.
    */
   public VarResolver getVarResolver() { return varResolver; }

   /**
    * Initializes this microservice.
    *
    * <p>
    * This method can be called whenever the microservice is not started.
    *
    * <p>
    * It will initialize (or reinitialize) the console commands, system properties, and logger.
    *
    * @return This object.
    * @throws ParseException Malformed input encountered.
    * @throws IOException Couldn't read a file.
    */
   public synchronized Microservice init() throws IOException, ParseException {

      // --------------------------------------------------------------------------------
      // Set system properties.
      // --------------------------------------------------------------------------------
      var spKeys = config.getKeys("SystemProperties");
      if (nn(spKeys))
         for (var key : spKeys)
            // Intentional real-JVM-property export: the [SystemProperties] config section is a documented
            // feature whose whole purpose is to push config entries into process-global system properties so
            // third-party libraries (e.g. SLF4J/logging adapters) that read raw System.getProperty pick them
            // up.  A Settings-based write would be invisible to those external consumers, so this is kept.
            System.setProperty(key, config.get("SystemProperties/" + key).orElse(null));

      // --------------------------------------------------------------------------------
      // Initialize logging.
      // --------------------------------------------------------------------------------
      logger.set(builder.logger);
      var logConfig = nn(builder.logConfig) ? builder.logConfig : new LogConfig();
      if (logger.get() == null) {
         LogManager.getLogManager().reset();
         logger.set(Logger.getLogger(""));
         var logFile = coalesce(logConfig.logFile, config.get("Logging/logFile").orElse(null));

         if (ine(logFile)) {
            var logDir = coalesce(logConfig.logDir, config.get("Logging/logDir").orElse("."));
            var logDirFile = resolveFile(logDir);
            mkdirs(logDirFile, false);
            logDir = logDirFile.getAbsolutePath();
            // Intentional real-JVM-property publish: the resolved log directory is exposed as a process-global
            // system property so external config and templates can reference it through the raw-reading
            // juneau.logDir SVL variable.  That variable reads the JVM property directly and bypasses the
            // Settings override chain, so a Settings-based write would not be visible to it.
            System.setProperty("juneau.logDir", logDir);

            var append = coalesce(logConfig.append, config.get("Logging/append").asBoolean().orElse(false));
            var limit = coalesce(logConfig.limit, config.get("Logging/limit").asInteger().orElse(1024 * 1024));
            var count = coalesce(logConfig.count, config.get("Logging/count").asInteger().orElse(1));

            var fh = new FileHandler(logDir + '/' + logFile, limit, count, append);

            var f = logConfig.formatter;
            if (f == null) {
               var format = config.get("Logging/format").orElse("[{date} {level}] {msg}%n");
               var dateFormat = config.get("Logging/dateFormat").orElse("yyyy.MM.dd hh:mm:ss");
               var useStackTraceHashes = config.get("Logging/useStackTraceHashes").asBoolean().orElse(false);
               f = new LogEntryFormatter(format, dateFormat, useStackTraceHashes);
            }
            fh.setFormatter(f);
            fh.setLevel(coalesce(logConfig.fileLevel, config.get("Logging/fileLevel").as(Level.class).orElse(Level.INFO)));
            logger.get().addHandler(fh);

            var ch = new ConsoleHandler();
            ch.setLevel(coalesce(logConfig.consoleLevel, config.get("Logging/consoleLevel").as(Level.class).orElse(Level.WARNING)));
            ch.setFormatter(f);
            logger.get().addHandler(ch);
         }
      }

      var loggerLevels = config.get("Logging/levels").as(JsonMap.class).orElseGet(JsonMap::new);
      for (var l : loggerLevels.keySet())
         Logger.getLogger(l).setLevel(loggerLevels.get(l, Level.class));
      for (var l : logConfig.levels.keySet())
         Logger.getLogger(l).setLevel(logConfig.levels.get(l));

      return this;
   }

   /**
    * Joins the application with the current thread.
    *
    * <p>
    * Default implementation is a no-op.
    *
    * @return This object.
    * @throws Exception Error occurred
    */
   public Microservice join() throws Exception {
      return this;
   }

   /**
    * Kill the JVM by calling <c>System.exit(2);</c>.
    */
   public void kill() {
      // This triggers the shutdown hook.
      System.exit(2);
   }

   @Override /* Overridden from ConfigChangeListener */
   public void onConfigChange(ConfigEvents events) {
      for (var l : beanStore.getBeansOfType(MicroserviceListener.class).values())
         l.onConfigChange(this, events);
   }

   /**
    * Prints a localized message to the console writer.
    *
    * <p>
    * Ignored if <js>"Console/enabled"</js> is <jk>false</jk>.
    *
    * @param mb The message bundle containing the message.  Must not be <jk>null</jk>.
    * @param messageKey The message key.
    * @param args Optional {@link MessageFormat}-style arguments.
    */
   public void out(Messages mb, String messageKey, Object...args) {
      var msg = mb.getString(messageKey, args);
      if (consoleEnabled)
         getConsoleWriter().println(msg);
      log(Level.INFO, msg);
   }

   /**
    * Start this application.
    *
    * <p>
    * Iterates over every {@link MicroserviceListener} bean in the {@linkplain #getBeanStore() bean store} (in
    * registration order) and calls {@link MicroserviceListener#onStart(Microservice)} on each.
    *
    * @return This object.
    * @throws Exception Error occurred.
    */
   public synchronized Microservice start() throws Exception {

      if (config.getName() == null)
         err(messages, "RunningClassWithoutConfig", cns(this));
      else
         out(messages, "RunningClassWithConfig", cns(this), config.getName());

      Runtime.getRuntime().addShutdownHook(new Thread("ShutdownHookThread") {
         @Override /* Overridden from Thread */
         public void run() {
            try {
               Microservice.this.stop();
               Microservice.this.stopConsole();
            } catch (Exception e) {
               getLogger().log(Level.WARNING, "Error occurred during microservice shutdown.", e);
            }
         }
      });

      for (var l : beanStore.getBeansOfType(MicroserviceListener.class).values())
         l.onStart(this);

      return this;
   }

   /**
    * Starts the console thread for this microservice.
    *
    * @return This object.
    * @throws Exception Error occurred
    */
   public synchronized Microservice startConsole() throws Exception {
      if (nn(consoleThread) && ! consoleThread.isAlive())
         consoleThread.start();
      return this;
   }

   /**
    * Stop this application.
    *
    * <p>
    * Iterates over every {@link MicroserviceListener} bean in the {@linkplain #getBeanStore() bean store} in
    * <i>reverse</i> registration order and calls {@link MicroserviceListener#onStop(Microservice)} on each, then
    * closes the bean store (firing any {@code @PreDestroy} hooks).
    *
    * @return This object.
    * @throws Exception Error occurred
    */
   public synchronized Microservice stop() throws Exception {
      if (stopped)
         return this;
      stopped = true;
      if (nn(settingsSource))
         Settings.get().removeSource(settingsSource);
      // Detach this microservice from JVM-global config state.  The config store (MemoryStore.DEFAULT) and
      // the system-default config slot are process-wide shared statics; leaving a stopped microservice
      // registered as a config-change listener there causes its onConfigChange() to fire against an
      // already-closed bean store when an unrelated component later mutates the shared config.
      if (nn(config)) {
         config.removeListener(this);
         if (Config.getSystemDefault() == config)
            Config.setSystemDefault(null);
      }
      var listeners = new ArrayList<>(beanStore.getBeansOfType(MicroserviceListener.class).values());
      Collections.reverse(listeners);
      for (var l : listeners)
         l.onStop(this);
      try {
         beanStore.close();
      } catch (Exception e) {
         // @PreDestroy errors should not prevent the rest of the shutdown sequence; surface via logger.
         var lg = getLogger();
         if (nn(lg))
            lg.log(Level.WARNING, localizedMessage(e), e);
      }
      return this;
   }

   /**
    * Stops the console thread for this microservice.
    *
    * @return This object.
    * @throws Exception Error occurred
    */
   public synchronized Microservice stopConsole() throws Exception {
      if (nn(consoleThread) && consoleThread.isAlive())
         consoleThread.interrupt();
      return this;
   }

   private List<String> getCandidateConfigNames() {
      if (nn(configName))
         return Collections.singletonList(configName);

      var args2 = getArgs();
      var configFile = args2.get("configFile");
      if (configFile.isPresent())
         return Collections.singletonList(configFile.get());

      var mainConfig = getManifest().get("Main-Config");
      if (mainConfig.isPresent())
         return Collections.singletonList(mainConfig.get());

      return Config.getCandidateSystemDefaultConfigNames();
   }

   /**
    * Returns the console reader.
    *
    * <p>
    * Subclasses can override this method to provide their own console input.
    *
    * @return The console reader, or <jk>null</jk> if the console is not enabled.
    */
   protected Scanner getConsoleReader() { return consoleReader; }

   /**
    * Returns the console writer.
    *
    * <p>
    * Subclasses can override this method to provide their own console output.
    *
    * @return The console writer, or <jk>null</jk> if the console is not enabled.
    */
   protected PrintWriter getConsoleWriter() { return consoleWriter; }

   private PrintWriter createLoggerConsoleWriter() {
      var fallbackLogger = coalesce(getLogger(), Logger.getLogger(cn(this)));
      return new PrintWriter(new Writer() {
         private final StringBuilder buffer = new StringBuilder();
         @Override
         public void write(char[] cbuf, int off, int len) throws IOException {
            for (var i = off; i < off + len; i++) {
               var ch = cbuf[i];
               if (ch == '\n') {
                  flushBuffer();
               } else if (ch != '\r') {
                  buffer.append(ch);
               }
            }
         }
         @Override
         public void flush() throws IOException {
            flushBuffer();
         }
         @Override
         public void close() throws IOException {
            flushBuffer();
         }
         private void flushBuffer() {
            if (! buffer.isEmpty()) {
               fallbackLogger.info(buffer.toString());
               buffer.setLength(0);
            }
         }
      }, true);
   }

   /**
    * Logs a message to the log file.
    *
    * @param level The log level.
    * @param message The message text.
    * @param args Optional {@link String#format(String, Object...) String.format}-style arguments.
    */
   protected void log(Level level, String message, Object...args) {
      var msg = args.length == 0 ? message : f(message, args);
      getLogger().log(level, msg);
   }

   /**
    * Resolves the specified path.
    *
    * <p>
    * If the working directory has been explicitly specified, relative paths are resolved relative to that.
    *
    * @param path The path to resolve.  Must not be <jk>null</jk>.
    * @return The resolved path.
    */
   protected File resolveFile(String path) {
      if (Paths.get(path).isAbsolute())
         return new File(path);
      if (nn(workingDir))
         return new File(workingDir, path);
      return new File(path);
   }
}