Habitat4JBootstrap, Habitat4JBootstrapServlet, and Examples

• 1.0 - Habitat4JBootstrap - Introduction
• 1.1 - Habitat4JBootstrap - Goals
• 1.2 - Habitat4JBootstrap - Bootstrap Parameters
• 1.3 - Habitat4JBootstrap - Bootstrap PropertyList File
• 1.4 - Habitat4JBootstrap - Application PropertyList System Files
• 1.5 - Habitat4JBootstrap - Application PropertyList Classpath Files

• 2.0 - Habitat4JBootstrapServlet - Servlet Configuration
• 2.1 - Habitat4JBootstrapServlet - Initialization Parameters (init-param)

• 3.0 - Examples - Bootstrap Code (Non-Servlet)
• 3.1 - Examples - Bootstrap PropertyList
• 3.2 - Examples - Application PropertyList (FileSystem)
• 3.3 - Examples - Application PropertyList (ClassPath)
• 3.4 - Examples - Web Descriptor (web.xml)

The "bootstrap" process occurs during the initialization, or start-up, phase of a Java application. Habitat4J makes available the Habitat4JBootstrap static Java class, which sets up Habitat4J for an application.

Habitat4JBootstrap, by default, uses a defined standard for the layout of an application's PropertyList files. This standard is described in this document.

Habitat4JBootstrapServlet is a wrapper for Habitat4JBootstrap. It provides identical functionality and only serves as a mechanism to pass parameters into Habitat4JBootstrap.

Habitat4JBootstrap provides a JVM-wide environment for Habitat4J, setting:

• Habitat4J's logger (System.out/err or log4j) and level
• XSD validation on/off
• Rules for reloading files while application is running
• Location of the server-wide server-identity.xml file
• Base location (directory) for PropertyList files located somewhere in the filesystem
• Base location (package) for PropertyList files located somewhere on the classpath
• Prefix and suffix conventions for PropertyList file names
• A list of PropertyList files to load

The following parameters are required by Habitat4JBootstrap:

• applicationName - This is specified as a String value containing the name of the application that will call Habitat4J.
• bootstrapPropertyListPath - This is specified as a String value containing the path to a very important configuration file, called the "bootstrap" configuration file. This file is described in this section. The path can be specified as a complete file path (e.g. c:/apps/myapp/properties-bootstrap.xml) or a classpath (e.g. org/productivity/java/myapp/properties-bootstrap.xml).

The following parameters are optional for use in Habitat4JBootstrap:

• xsdValidationEnabled - This is specified as a boolean value which determines whether Habitat4J should validate the server-identity and property-list files against the stock Habitat4J XSD files.
• log4jEnabled - This is specified as a boolean value which determines whether Habitat4J should use log4j
• logLevel - This is specified as a String value containing one of the following log levels: debug, info, warn, error, or fatal mainly used for setting Habitat4J's native logging level (non-log4j).
• serverIdentityFilePath - This is specified as a String containing a single path or semicolon-delimited list of paths pointing to the location of a server-identity.xml file. If a semicolon-delimited list is provided, the first location (searching left to right) that contains a server-identity.xml file will be used.
• appPropertyListLoaderClassName - This is specified as a String containing the fully qualified class for the customized a custom implementation of ApplicationPropertyListLoaderIF.

NOTE: Only one of the following calls to Habitat4JBootstrap.initialize(..) is required. Examples start from the simplest and end with the most specific initialize(..) method.

The following code will initialize Habitat4J using a Bootstrap PropertyList file from the classpath:

  Habitat4JBootstrap.initialize(
    "MyApplication",
    "org/productivity/java/myapp/properties-bootstrap.xml"
  );

The following code will initialize Habitat4J using a Bootstrap PropertyList file from the filesystem:

  Habitat4JBootstrap.initialize(
    "MyApplication",
    "c:/apps/myapp/properties-bootstrap.xml"
  );

The following code will initialize Habitat4J with XSD validation enabled:

  Habitat4JBootstrap.initialize(
    "MyApplication",
    "org/productivity/java/myapp/properties-bootstrap.xml",
    true
  );

The following code will initialize Habitat4J with XSD validation enabled and Log4J support enabled:

  Habitat4JBootstrap.initialize(
    "MyApplication",
    "org/productivity/java/myapp/properties-bootstrap.xml",
    true,
    true
  );

The following code will initialize Habitat4J with XSD validation enabled, Log4J support disabled, and the built-in Habitat4J Logger set to "warn" level:

  Habitat4JBootstrap.initialize(
    "MyApplication",
    "org/productivity/java/myapp/properties-bootstrap.xml",
    true,
    false,
    "warn"
  );

The following code will initialize Habitat4J with XSD validation enabled, Log4J support enabled, and the path of the server-identity.xml file explicitly specified:

  Habitat4JBootstrap.initialize(
    "MyApplication",
    "org/productivity/java/myapp/properties-bootstrap.xml",
    true,
    false,
    null,
    "c:/winnt/server-identity.xml"
  );

The following code will initialize Habitat4J with XSD validation enabled, Log4J support enabled, the path of the server-identity.xml file explicitly specified, and a custom ApplicationPropertyListLoaderIF implementation:

  Habitat4JBootstrap.initialize(
    "MyApplication",
    "org/productivity/java/myapp/properties-bootstrap.xml",
    true,
    false,
    null,
    "c:/winnt/server-identity.xml",
    MyAppPropertyListLoader.class
  );

The following code will initialize Habitat4J with XSD validation enabled, Log4J support enabled, the path of the server-identity.xml file explicitly specified, and a custom ApplicationPropertyListLoaderIF implementation (specified by String):

  Habitat4JBootstrap.initialize(
    "MyApplication",
    "org/productivity/java/myapp/properties-bootstrap.xml",
    true,
    false,
    null,
    "c:/winnt/server-identity.xml",
    "org/productivity/java/myapp/MyAppPropertyListLoader"
  );