From JVM Process to Bootstrap Layer

Bootstrap is the first Tomcat code that runs in the JVM. It executes once per process, prepares the runtime environment, then hands off to org.apache.catalina.startup.Catalina, which manages the server lifecycle and request handling.

Process / Startup View

+----------------------------------------------------------+
|  JVM Process                                             |
|                                                          |
|  org.apache.catalina.startup.Bootstrap                   |
|  ------------------------------------------------------  |
|  - static init:                                          |
|      * resolve catalinaHomeFile / catalinaBaseFile       |
|      * set System properties                             |
|  - initClassLoaders():                                   |
|      * commonLoader   (from common.loader)               |
|      * catalinaLoader (from server.loader, parent=common)|
|      * sharedLoader   (from shared.loader, parent=common)|
|  - init():                                               |
|      * Thread.contextClassLoader = catalinaLoader        |
|      * load "org.apache.catalina.startup.Catalina"      |
|      * create catalinaDaemon instance                    |
|      * call setParentClassLoader(sharedLoader)           |
|  - main(args):                                           |
|      * synchronize on daemonLock                         |
|      * create/reuse Bootstrap daemon                     |
|      * parse last arg as command                         |
|      * dispatch to load/start/stop/stopServer/etc.       |
|                                                          |
+-----------------------|----------------------------------+
                        v
           org.apache.catalina.startup.Catalina
           (container lifecycle, request handling, etc.)

Everything in Bootstrap serves three responsibilities:

• Resolve and publish CATALINA_HOME and CATALINA_BASE.
• Build a controlled class loader hierarchy from configuration.
• Reflectively load, configure, and drive the Catalina daemon based on commands like start, stop, and configtest.

Owning the Environment: Home, Base, and Class Loaders

Once we view Bootstrap as its own layer, the first job is to tame the environment. Tomcat must run in different layouts (packages, tarballs, local dev), so it can’t assume a fixed path structure. Bootstrap takes that pain on itself.

Resolving CATALINA_HOME and CATALINA_BASE

The static initializer runs as soon as Bootstrap is loaded. It tries a sequence of strategies to find the installation directory (CATALINA_HOME) and the instance directory (CATALINA_BASE), then publishes them as system properties:

static {
    String userDir = System.getProperty("user.dir");

    String home = System.getProperty(Constants.CATALINA_HOME_PROP);
    File homeFile = null;

    if (home != null) {
        File f = new File(home);
        try {
            homeFile = f.getCanonicalFile();
        } catch (IOException ioe) {
            homeFile = f.getAbsoluteFile();
        }
    }

    if (homeFile == null) {
        File bootstrapJar = new File(userDir, "bootstrap.jar");
        if (bootstrapJar.exists()) {
            File f = new File(userDir, "..");
            try {
                homeFile = f.getCanonicalFile();
            } catch (IOException ioe) {
                homeFile = f.getAbsoluteFile();
            }
        }
    }

    if (homeFile == null) {
        File f = new File(userDir);
        try {
            homeFile = f.getCanonicalFile();
        } catch (IOException ioe) {
            homeFile = f.getAbsoluteFile();
        }
    }

    catalinaHomeFile = homeFile;
    System.setProperty(Constants.CATALINA_HOME_PROP,
                       catalinaHomeFile.getPath());

    String base = System.getProperty(Constants.CATALINA_BASE_PROP);
    if (base == null) {
        catalinaBaseFile = catalinaHomeFile;
    } else {
        File baseFile = new File(base);
        try {
            baseFile = baseFile.getCanonicalFile();
        } catch (IOException ioe) {
            baseFile = baseFile.getAbsoluteFile();
        }
        catalinaBaseFile = baseFile;
    }
    System.setProperty(Constants.CATALINA_BASE_PROP,
                       catalinaBaseFile.getPath());
}

The pattern here is deliberate:

• Prefer explicit configuration via system properties.
• If absent, infer from the current working directory and known layout (for example, bin/bootstrap.jar).
• As a last resort, assume the current directory.
• Publish the resolved values exactly once as system properties for the rest of the codebase.

This keeps environment probing localized in one place and ensures every other component sees stable, canonical paths.

Turning loader strings into a class loader graph

With CATALINA_HOME and CATALINA_BASE set, Bootstrap builds a layered class loader hierarchy to separate Tomcat internals from user code. It creates three loaders:

• commonLoader: shared libraries visible to both container and webapps.
• catalinaLoader: Tomcat’s own implementation classes.
• sharedLoader: optional shared libraries for web applications.

Each loader is configured by a property like common.loader, whose value is a string of paths and URLs. The heart of this translation is createClassLoader:

private ClassLoader createClassLoader(String name, ClassLoader parent)
        throws Exception {

    String value = CatalinaProperties.getProperty(name + ".loader");
    if (value == null || value.isEmpty()) {
        return parent;
    }

    value = replace(value); // variable expansion

    List repositories = new ArrayList<>();
    String[] repositoryPaths = getPaths(value);

    for (String repository : repositoryPaths) {
        try {
            URI uri = new URI(repository);
            uri.toURL();
            repositories.add(new Repository(repository, RepositoryType.URL));
            continue;
        } catch (IllegalArgumentException | MalformedURLException
                 | URISyntaxException e) {
            // Not a URL - treat as local path
        }

        if (repository.endsWith("*.jar")) {
            String base = repository.substring(0,
                repository.length() - "*.jar".length());
            repositories.add(new Repository(base, RepositoryType.GLOB));
        } else if (repository.endsWith(".jar")) {
            repositories.add(new Repository(repository, RepositoryType.JAR));
        } else {
            repositories.add(new Repository(repository, RepositoryType.DIR));
        }
    }

    return ClassLoaderFactory.createClassLoader(repositories, parent);
}

There are a few design choices worth copying:

• Stringly-typed at the edges only. Configuration arrives as a string but is immediately turned into Repository objects with a RepositoryType enum. Downstream code never re-parses magic suffixes.
• Globs normalized early. The *.jar convention becomes a GLOB repository type once, instead of being reinterpreted on every lookup.
• URLs identified by URI parsing, not ad-hoc checks. Attempting new URI(...) and toURL() is more robust than homegrown heuristics.

Parsing loader paths and failing fast

The loader string can be a comma-separated list of paths and URLs, possibly with spaces and quotes. Bootstrap delegates this to getPaths, which uses a precompiled pattern to iterate over segments and then validates quoting:

static String[] getPaths(String value) {
    List result = new ArrayList<>();
    Matcher matcher = PATH_PATTERN.matcher(value);

    while (matcher.find()) {
        String path = value.substring(matcher.start(), matcher.end()).trim();
        if (path.isEmpty()) {
            continue;
        }

        char first = path.charAt(0);
        char last = path.charAt(path.length() - 1);

        if (first == '"' && last == '"' && path.length() > 1) {
            path = path.substring(1, path.length() - 1).trim();
            if (path.isEmpty()) {
                continue;
            }
        } else if (path.contains("\"")) {
            throw new IllegalArgumentException(
                "The double quote [\"] character can only be used to " +
                "quote paths. It must not appear in a path. This loader " +
                "path is not valid: [" + value + "]");
        }

        result.add(path);
    }

    return result.toArray(new String[0]);
}

This illustrates a recurring principle in Bootstrap: parse hard, fail early. It does not try to salvage almost-valid configs; it rejects them with a clear exception, long before any requests are served.

Reflection as a Narrow Remote Control

Once the class loaders exist, Bootstrap needs to create and control Catalina—but it cannot depend on that class directly. Catalina lives in the class path that Bootstrap just constructed. The solution is to treat reflection as a tiny, well-bounded remote control.

Initializing the daemon

init() does three things in order: build class loaders, set the thread context class loader, and use that loader to reflectively create and configure a Catalina instance:

public void init() throws Exception {
    initClassLoaders();

    Thread.currentThread().setContextClassLoader(catalinaLoader);

    Class startupClass =
        catalinaLoader.loadClass("org.apache.catalina.startup.Catalina");
    Object startupInstance = startupClass.getConstructor().newInstance();

    Class[] paramTypes =
        new Class[] { Class.forName("java.lang.ClassLoader") };
    Object[] paramValues = new Object[] { sharedLoader };

    Method method = startupInstance.getClass()
        .getMethod("setParentClassLoader", paramTypes);
    method.invoke(startupInstance, paramValues);

    catalinaDaemon = startupInstance;
}

After this point, Bootstrap treats catalinaDaemon as an opaque handle. Only a few lifecycle methods ever touch reflection again.

Lifecycle commands as thin reflective wrappers

The public methods that power CLI commands (start, stop, load, stopServer, setAwait) are intentionally boring wrappers around reflective calls. For example:

public void start() throws Exception {
    if (catalinaDaemon == null) {
        init();
    }
    Method method = catalinaDaemon.getClass()
        .getMethod("start", (Class[]) null);
    method.invoke(catalinaDaemon, (Object[]) null);
}

public void stop() throws Exception {
    Method method = catalinaDaemon.getClass()
        .getMethod("stop", (Class[]) null);
    method.invoke(catalinaDaemon, (Object[]) null);
}

The implementation is repetitive by design: the reflection surface area is small, explicit, and easy to reason about. The report proposes a simple refactor—introducing a helper like invokeOnDaemon(String methodName, Class[] types, Object[] args)—to reduce duplication and centralize logging and error handling. That doesn’t change the architecture; it tightens the boundary.

Startup as a Single, Observable Transaction

The real test for any bootstrap layer is how it behaves when something goes wrong. Bootstrap makes two important choices: treat startup as a single, idempotent transaction, and own the process’s exit policy.

Command dispatch and idempotent init

The main method initializes the daemon once under a lock, then dispatches on the last CLI argument as the command:

public static void main(String[] args) {
    synchronized (daemonLock) {
        if (daemon == null) {
            Bootstrap bootstrap = new Bootstrap();
            try {
                bootstrap.init();
            } catch (Throwable t) {
                handleThrowable(t);
                log.error("Init exception", t);
                return;
            }
            daemon = bootstrap;
        } else {
            Thread.currentThread().setContextClassLoader(
                daemon.catalinaLoader);
        }
    }

    try {
        String command = (args.length > 0)
            ? args[args.length - 1] : "start";

        switch (command) {
            case "startd":
                args[args.length - 1] = "start";
                daemon.load(args);
                daemon.start();
                break;
            case "stopd":
                args[args.length - 1] = "stop";
                daemon.stop();
                break;
            case "start":
                daemon.setAwait(true);
                daemon.load(args);
                daemon.start();
                if (daemon.getServer() == null) {
                    System.exit(1);
                }
                break;
            case "stop":
                daemon.stopServer(args);
                break;
            case "configtest":
                daemon.load(args);
                if (daemon.getServer() == null) {
                    System.exit(1);
                }
                System.exit(0);
                break;
            default:
                log.warn("Bootstrap: command \"" + command
                         + "\" does not exist.");
        }
    } catch (Throwable t) {
        Throwable root = (t instanceof InvocationTargetException
                          && t.getCause() != null)
                       ? t.getCause() : t;
        handleThrowable(root);
        log.error("Error running command", root);
        System.exit(1);
    }
}

The lock around initialization means init() runs at most once per process, even if main is re-entered through a service wrapper. After that, daemon is reused, and only the context class loader is reset for the current thread. That’s a straightforward implementation of idempotent initialization.

Exit codes as part of the contract

Bootstrap turns key failure modes into explicit exit codes:

• Startup fails before command dispatch: logs “Init exception” and returns; external scripts typically treat the lack of a running process as failure.
• start completes but getServer() is null: exits with status 1.
• configtest: exits 1 if the server is invalid, 0 if configuration is valid.
• Unhandled exceptions in command handling: unwrapped, logged, then exit 1.

The analysis suggests an incremental improvement: extract System.exit calls behind a simple ExitHandler interface so tests and embedded use can override the behavior. The core point stands, though: the bootstrap layer is the right place to centralize process exit policy.

A minimal but deliberate throwable handler

To avoid depending on broader Tomcat utilities during very early startup, Bootstrap includes its own tiny throwable handler:

static void handleThrowable(Throwable t) {
    if (t instanceof StackOverflowError) {
        return; // let caller decide, avoid making it worse
    }
    if (t instanceof VirtualMachineError) {
        throw (VirtualMachineError) t; // unrecoverable
    }
    // All other Throwables are ignored here; callers log and exit
}

The choices are narrow but intentional:

• VirtualMachineError (for example, OutOfMemoryError) is rethrown so the JVM can crash; recovery is unrealistic.
• StackOverflowError is silently ignored to avoid deepening the stack; the caller is expected to log and exit.
• Everything else is left to the calling site, which always pairs handleThrowable with logging and, when appropriate, System.exit.

The smell the report identifies is that this handler can swallow serious errors if misused. The fix isn’t more logic here; it is to keep its usage confined and always follow it with logging—exactly what init(), initClassLoaders(), and main() already do.

Shaping startup for observability

Even though Bootstrap predates modern observability stacks, its linear control flow makes metrics easy to add. The performance profile points at natural instrumentation points:

• Time from main() entry to successful start (a startup duration metric).
• Counters around class loader creation failures in initClassLoaders().
• Command-level failure counts around the switch in main().

The important part is structural: main is a single entry point, sub-operations are explicit methods, and error surfaces are small and well-defined. That makes it straightforward to wrap these pieces with timers and counters without changing behavior.

Design Patterns to Steal for Your Own Bootstraps

Walking through Bootstrap.java gives us a concrete model for treating startup as its own layer. The primary lesson is clear: give bootstrap its own responsibilities and let it aggressively clean up the world before your main logic runs. Here are the patterns worth reusing.

1. Make bootstrap a first-class architectural layer

• Let it know about environment quirks: directory layouts, system properties, defaults, and fallbacks live here, not spread across business logic.
• Keep its dependencies minimal to avoid chicken-and-egg problems during early class loading.
• Make it the explicit owner of process startup and exit semantics.

2. Parse and normalize configuration at the edge

• Resolve variables and paths once (like replace() and the home/base static block) and publish canonical values.
• Turn complex strings into structured objects early—getPaths() and createClassLoader() mean no other component has to reason about quotes, commas, or special suffixes.
• Fail fast on malformed input instead of trying to be forgiving and silently wrong.

3. Confine reflection behind a tiny façade

• Accept that reflection is sometimes necessary (for example, when loading classes through custom class loaders) but keep it localized.
• Store reflected instances behind opaque handles and expose only well-defined wrapper methods.
• Consider centralizing reflective calls into a helper to keep logging and error handling consistent.

4. Treat startup as a single transaction with an explicit contract

• Initialize once under a lock and reuse the resulting state; don’t rebuild discovery logic on every command invocation.
• Own the mapping from failure modes to exit codes in one place, so external orchestrators (systemd, Kubernetes, custom scripts) get predictable signals.
• Structure control flow so that it’s easy to attach metrics and logs to each stage.

5. Keep early error handling simple and visible

• In early startup, avoid complex error handling stacks; small helpers like handleThrowable are easier to audit.
• Let truly unrecoverable conditions fail hard, and require callers to pair any swallowing of Throwable with explicit logging.

Viewed this way, Tomcat’s Bootstrap is more than a Java version of a shell script. It’s a compact example of how to:

• Isolate environment-specific concerns into one layer.
• Convert stringly configuration into structured state at the edges.
• Use reflection surgically instead of letting it leak everywhere.
• Shape startup into a single, observable transaction with a clear exit contract.

The next time you’re bringing a complex service to life, it’s worth asking: do you have a clear, opinionated bootstrap layer like this, or are you letting the rest of the codebase bootstrap itself piecemeal? In practice, that “silent script” is often the difference between a system that usually starts and one you can operate confidently at scale.