| A main(String[] args) class that searches for classes and
jar files in a path, creates an
XURLClassLoader that uses
the found jars, and launches an application class (typically a
Cougaar Node).
The Bootstrapper simplifies the
$COUGAAR_INSTALL_PATH/bin/cougaar
script and similar run scripts, which use the bootstrapper's jar
for their Java classpath, instead of listing many individual jar
files. For example, instead of:
java
-classpath /tmp/classes:/jars/lib/a.jar:/jars/lib/b.jar:/jars/lib/c.jar
MyClass
one can write:
java
-Dorg.cougaar.class.path=/tmp/classes
-Dorg.cougaar.install.path=/jars
-jar bootstrap.jar
MyClass
or the equivalent:
java
-classpath bootstrap.jar
-Dorg.cougaar.class.path=/tmp/classes
-Dorg.cougaar.install.path=/jars
org.cougaar.bootstrap.Bootstrapper
MyClass
Note that the "-classpath" should only specify the
Bootstrapper's jar. See the "Important Notes" below for further
details.
The application classname can be specified by either the:
-Dorg.cougaar.bootstrap.application=CLASSNAME
system property or as the first command-line argument to this
Bootstrapper class's
Bootstrapper.main method. The class must
provide a public static launch(String[]) or
main(String[]) method (searched for in that order).
If additional command-line arguments are specified, they are
passed along to the application class's method.
The default jar search path is specified by the:
-Dorg.cougaar.jar.path=
Bootstrapper.DEFAULT_JAR_PATH
system property. In standard configurations this path is
expanded to (approximately) the following jars:
$COUGAAR_INSTALL_PATH/lib/*.jar
$COUGAAR_INSTALL_PATH/sys/*.jar
The exact list of jars is controlled by "-Dorg.cougaar.jar.path".
The separator character is ":" on Linux, ";" on Windows, and ","
on both. The jar path defaults to the
Bootstrapper.DEFAULT_JAR_PATH value of:
-Dorg.cougaar.jar.path=\
classpath($CLASSPATH):\
$RUNTIME/lib:\
$RUNTIME/sys:\
$SOCIETY/lib:\
$SOCIETY/sys:\
$INSTALL/lib:\
$INSTALL/plugins:\
$SYS:\
$INSTALL/sys
where:
$CLASSPATH is the optional -Dorg.cougaar.class.path
$RUNTIME is the optional -Dorg.cougaar.runtime.path
$SOCIETY is the optional -Dorg.cougaar.society.path
$INSTALL is the optional -Dorg.cougaar.install.path
$SYS is the optional -Dorg.cougaar.system.path
If any of the above "$VARIABLE" system properties is not set, then the
corresponding paths in the default jar path will be excluded. For example,
if only the "-Dorg.cougaar.install.path" is set, then the default jar path
will be:
-Dorg.cougaar.jar.path=$INSTALL/lib:$INSTALL/plugins:$INSTALL/sys
The "classpath(..)" path wrapper is used to list jars and
directories containing classes, similar to Java's CLASSPATH.
For example:
-Dorg.cougaar.class.path=/tmp/classes:/tmp/foo.jar
The default path wrapper, "directory(..)", is used to find jars
in a directory by listing "*.jar", "*.zip", and "*.plugin".
For example:
-Dorg.cougaar.system.path=/jars
where "/jars" contains jar files, for example:
/jars/a.jar
/jars/b.jar
/jars/c.jar
If the "-Dorg.cougaar.jar.path" value ends in the separator character,
then the
Bootstrapper.DEFAULT_JAR_PATH is appended to the end of the specified
value. This can be used to easily prefix the jar path.
Note that the above "$" strings must be escaped to avoid Unix
shell expansion, for example:
-Dorg.cougaar.jar.path=\\\$INSTALL/lib:\\\$INSTALL/sys
In practice the "$" strings are rarely used, since explicit paths
are often specified, for example:
-Dorg.cougaar.jar.path=/tmp/lib:classpath(/tmp/classes):/tmp/sys
The $CLASSPATH "-Dorg.cougaar.class.path" is primarily a developer
mechanism to override the infrastructure and application jars with
development code. Most packaged Cougaar applications do not use
these optional system properties, and instead create jar files for
$INSTALL/lib.
A couple jars are typically excluded by the jar finder, and
instead are loaded by the Java system ClassLoader:
bootstrap.jar (contains this Bootstrapper class)
javaiopatch.jar (contains the persistence I/O overrides)
These excluded jars are set by:
-Dorg.cougaar.bootstrap.excludeJars=javaiopatch.jar:bootstrap.jar
Important Notes:
If you use the Bootstrapper, do not put Cougaar classes on your
Java classpath -- only specify:
java -classpath bootstrapper.jar ..
If the Java SystemClassloader loads a Cougaar class, it will refer
to SystemClassloader-loaded core classes which exist in a different
namespace than Bootstrapper-loaded classes. This problem will
cause all sorts of loading errors.
A common problem is the attempt to use "patch" jar files to repair
a few classes of some much larger archive. There are two problems
with this use pattern:
- The order that Bootstrapper will find jar files in a directory
is undefined - there is no guarantee that the patch will take
precedence over the original.
- Classloaders will refuse to load classes of a given package
from multiple jar files - if the patch jar does not contain the
whole package, the classloader will likely be unable to load the
rest of the classes.
Both problems tend to crop up when you can least afford this confusion.
Bootstrapper.DEFAULT_JAR_PATH | 