Command-line Usage

forhead is a command-line utility that handles all classpath and classloader issues for the application it wraps. You may configure a complex hierarchy of classloaders to exactly define from where each class within your application gets loaded.

To use forehead, you will typically write a small Unix shell script or a Windows batch script that invokes forehead with the appropriate arguments, such as:

    java -DmyApp.home=/path/to/myApp \
         -Dforehead.conf.file=/path/to/my/forehead.conf \
         com.werken.forehead.Forehead $*

forehead will configure itself based upon the contents of the file it locates using the forehead.conf.file system property. The forehead.conf file will be described in the next section.

Format of forehead.conf

There are 3 main features of a forehead.conf file:

1. Property Imports
2. ClassLoader Definitions
3. Entry-point Definition

Property Imports

When defining the paths and jars that are a part of the classpath for one of your ClassLoaders, it is many times convenient to reference a value stored in a Java system property. For example, your script that and invokes forehead my set a property such as myApp.home to the location within the filesystem that your application is installed. Within the forehead.conf file, this property may be referenced using ${myApp.home} notation.

To make a property available within a forehead.conf file, it must first be imported using the following syntax:

+property.name.one
+property.name.two
+property.name.three

For example:

+myApp.home

ClassLoader Definitions

Complex hierarchies of ClassLoaders may be constructed using a forehead.conf file. Each ClassLoader definition starts with the name of the ClassLoader within square brackets, and is followed by the paths to include in the search path for the loader. URLs are allowed.

ClassLoader names uses dot-notation to specify the hierarchy. A ClassLoader may only be defined after its parent has been defined.

For example:

+tools.jar.path
+myApp.home

[root]
    ${tools.jar.path}

[root.app]
    ${myApp.home}/lib/myApp.jar
    ${myApp.home}/lib/someDependency.jar

Entry-point Definition

Each forehead.conf file must contain exactly 1 entry-point definition. This specifies which class should be loaded from which ClassLoader. The entry-point's normal main(String[]) method will be invoked. Additionally, the thread's context ClassLoader will be set to that which loaded the entry-point class.

The syntax for an entry-point definition is as follows:

= [ClassLoader name] class name

For example:

= [root.app] com.myco.myapp.Main

Complete Example

Here is a complete example from the jakarta-turbine-maven project:

# Import some properties
#
+maven.home
+java.home
+tools.jar

# Define the entry-point as:
#
#   void org.apache.maven.app.Maven::main(String[])
#
# Attempt to load through the [root.maven] # classloader,
# but it may actually be loaded higher in the hierarchy
#
=[root.maven] org.apache.maven.app.Maven

# Define a classloader named [root]
#
[root]

    # Path elements searched loaded in-order

    ${tools.jar}
    ${maven.home}/lib/grant-1.0-dev.jar
    ${maven.home}/lib/ant-1.4.1.jar
    ${maven.home}/lib/xercesImpl-2.0.0.jar
    ${maven.home}/lib/xmlParserAPIs-2.0.0.jar
    ${maven.home}/lib/ant-optional-1.4.1.jar
    ${maven.home}/lib/junit-3.7.jar
    ${maven.home}/lib/xmlParserAPIs-2.0.0.jar

# Define a classloader named [root.mave], which has
# [root] as a parent.
#
[root.maven]
    ${maven.home}/lib/xercesImpl-2.0.0.jar
    ${maven.home}/lib/commons-jelly-1.0-dev.20020614.035258.jar
    ${maven.home}/lib/werkz-1.0-dev.20020613.091536.jar
    ${maven.home}/lib/commons-logging-1.0.jar
    ${maven.home}/lib/log4j-1.1.3.jar
    ${maven.home}/lib/dom4j-1.4-dev.jar
    ${maven.home}/lib/commons-beanutils-1.4-dev.jar
    ${maven.home}/lib/commons-collections-2.0.jar
    ${maven.home}/lib/commons-jexl-1.0-dev.jar
    ${maven.home}/lib/antlr-2.7.1.jar
    ${maven.home}/lib/bcel-5.0.jar
    ${maven.home}/lib/checkstyle-2.2.jar
    ${maven.home}/lib/commons-betwixt-1.0-dev.jar
    ${maven.home}/lib/commons-cli-1.0-dev.jar
    ${maven.home}/lib/commons-digester-1.2.jar
    ${maven.home}/lib/commons-graph-0.8.jar
    ${maven.home}/lib/commons-io-0.1.jar
    ${maven.home}/lib/commons-lang-1.0-dev.jar
    ${maven.home}/lib/commons-util-1.0-rc2-dev.jar
    ${maven.home}/lib/jdepend-2.2.jar
    ${maven.home}/lib/logkit-1.0.1.jar
    ${maven.home}/lib/oro-2.0.6.jar
    ${maven.home}/lib/regexp-1.2.jar
    ${maven.home}/lib/velocity-1.4-dev.jar
    ${maven.home}/lib/velocity-dvsl-0.43.jar
    ${maven.home}/lib/maven.jar
    ${maven.home}/lib/commons-logging-1.0.jar
    ${maven.home}/lib/log4j-1.1.3.jar