Introduction

Purpose

In order to reduce the number of classloading projects, classworlds replaces forehead for application launching.

The main problems to solve in application launching include locating all of application's JARs, configuring the initial classloaders, and invoking the main entry method.

The launcher facilities of classworlds simplify the process of locating application jars. A common idiom is to have a script which starts the JVM with only the classworlds.jar in the classpath and a system property to specify the location of a launcher configuration. Additionally, typically a property specifying the installation location is passed on the command-line.

$JAVA_HOME/bin/java \
    -classpath $APP_HOME/lib/classworlds-1.0.jar \
    -Dclassworlds.conf=$APP_HOME/etc/classworlds.conf \
    -Dapp.home=$APP_HOME \
    org.codehaus.classworlds.Launcher \
    $*

Configuration

Entry Definition

The entry-point class and realm must be specified using the main is directive before specifying realm definitions.

main is com.werken.projectz.Server from app

Realm Definitions

At least one classworlds realm must be defined within the configuration file. The syntax for starting a realm definition is [realm.name]. All lines following the realm header are considered directives for that realm. The realm definition continues either until another realm is defined or until the end of the file is reached.

[realm.one]
    ...
    ...

[realm.two]
    ...
    ...

[realm.three]
    ...
    ...

Within a realm definition, two directives are available: load and import.

The load directive specifies a class source to be used for loading classes in the realm. Any loaded source that ends with the / character is considered a directory hierarchy of classes and resources and all others are considered to be JAR files. System properties may be referred to using ${propname} notation. The load directive is equivelent to the addConstituent(..) method of ClassRealm.

[app]
    load ${app.home}/lib/myapp.jar
    load ${app.home}/lib/xerces.jar
    load ${tools.jar}

The import directive specifies that certain packages should be imported and loaded by way of another realm. The import directive is equivelent to the importFrom(..) method of ClassRealm.

[app]
    ...
  
[subcomponent]
    import com.werken.projectz.Foo from [app]
    ...

Entry point methods

classworlds can be used to invoke any existing application's main() method. Using the standard entry point does not allow for gaining access to the ClassWorld of the application, but not all applications will need it at run-time.

For those applications that do require the ClassWorld instance, an alternative entry-point method signature can be provide. Simply add a ClassWorld parameter to the standard main parameter list.

public class MyApp
{
    public static void main(String[] args,
                            ClassWorld world)
    {
        ...     
    }
}