Introduction

The JBoss Bootstrap project is responsible for creating generic runtimes based off an externally-defined user configuration.  Its primary client is the JBoss Application Server, but the design is adaptable to be consumed by any project seeking a simplified lifecycle and configuration API.

Modules

Project Information

Release Plan

History and Overview

Originally contained in the "bootstrap" module of the Application Server, org.jboss.bootstrap:jboss-bootstrap was extracted into its own component with separate release cycle in late 2008 (https://jira.jboss.org/jira/browse/JBBOOT-1).  After successful re-introduction into the AS as a thirdparty library, the existing implementation was copied into the "legacy" module where it resides today for maintenance purposes.

The new 2.0.0-series of org.jboss.bootstrap was later built alongside the legacy package, split into 3 logical scopes: Generic Bootstrap, Microcontainer-backed Servers, and JBoss AS-specific Servers.  Each scope was given a default implementation (impl-*) of its own SPI (spi-*) and a client view (api-*) as separate subcomponents in order to facilitate:

1) Hiding internals from a consuming project's compilation dependency chain
2) Freezing the API/SPI versions independently of the implementation

3) Hiding implementation demands on providers from the client view

The bootstrap projects center around the protagonist of a "Server", which is defined as a simple, stateful container with some rudimentary lifecycle.  In turn, the Server is responsible for management of a main "Bootstrap", which defines the set of services which are to be deployed into the runtime.  Thus, the focus of jboss-bootstrap is to maintain a slim, intuitive facade as the unified access point for user-defined profiles.  This concept may be expanded to fully realize the modular goals of JBoss Reloaded, standalone modes for AS subprojects, or other custom Servers.

The Boot Process

Starting up a Server backed by JBoss Bootstrap typically involves the following:

• Create a Server
  • Either via a factory or direct instanciation
  • ClassLoading is the responsibility of the client
    
• Point the Server to a backing Bootstrap configuration XML URL
  
  • Defaults are provided
  • ServerConfig.bootstrapUrl is authoritative
  • In the absense of "bootstrapUrl", this is constructed from a combination of "boostrapHome" and "bootstrapName"
    • If Bootstrap Home: "file:/home/user/bootstrap"
    • ..and Bootstrap Name: "bootstrap.xml"
    • ...then Bootstrap URL becomes: "file:/home/user/bootstrap/bootstrap.xml"
• Start the Server
• Configuration will become frozen and immutable
  
• The server will advance through its lifecycle to "start", firing any lifecycle state change callbacks along the way.
• During the "STARTING" phase, the Server will parse out the contents of the bootstrap and deploying each of its referents.
• Server state becomes "STARTED"
• Do any work
  
• Shutdown the server.  Lifecycle events will fired for each state change. 
  
• The Server may be later restarted.  Configuration remains immutable.

The Configurable Bootstrap XML

A Bootstrap contains references to deployable URLs and directs the Server to process them in order.  This makes the Bootstrap itself imply an aggreator used to collect other services into a unified configuration.  An example of a valid bootstrap XML descriptor looks like:

<?xml version="1.0" encoding="UTF-8"?>
<bootstrap xmlns="urn:jboss:bootstrap:1.0">

    <!-- References to deployable configurations -->
    <url>some-services.xml</url>
    <url>more-stuff.xml</url>

</bootstrap>

Related

• Application Server
• JBoss Reloaded Design
• JBossMCProfileServiceBootstrap

Caveats and Gotchas

• JBoss Bootstrap | ClassLoading