diff --git a/src/site/markdown/apiusage.md b/src/site/markdown/apiusage.md new file mode 100644 index 00000000..6cfbacc1 --- /dev/null +++ b/src/site/markdown/apiusage.md @@ -0,0 +1,76 @@ +--- +title: Classworlds API Usage +author: bob mcwhirter +--- + +# Classworlds API Usage + +The Java API can be used to create new realms and connect +realms together through importation of specific packages. + +The core of the **Classworlds** infrastructure is +the +[ClassWorld](apidocs/index.html?org/codehaus/plexus/classworlds/ClassWorld.html) +class. An application must create a `ClassWorld` instance. +It is advisable to store the instance as a singleton or some other +handy location. + +``` + +ClassWorld world = new ClassWorld(); + +``` + +Once a `ClassWorld` is created, realms within it +can be created. These realms effectively only allow loading +of the core JVM classes initially. + +``` + +ClassWorld world = new ClassWorld(); +ClassRealm containerRealm = world.newRealm( "container" ); +ClassRealm logComponentRealm = world.newRealm( "logComponent" ); + +``` + +In order to make each `ClassRealm` useful, constituents +in form of URLs must be added to it where each can provide certain classes. +The URL must return either a JAR or a directory on the default file system. + +``` + +containerRealm.addURL( containerJarUrl ); +logComponentRealm.addURL( logComponentJarUrl ); + +``` + +`ClassRealm`s can optionally be filtered to further restrict which classes/resources +are exposed. The filter is provided as additional argument to `world.newRealm( "filteredcontainer", myPredicate );` + +Now, links between the various realms need to be created to allow +classes loaded from one to be available to classes loaded in another. + +``` + +logComponentRealm.importFrom( "container", + "com.werken.projectz.component" ); + +``` + +The container implementation can then be loaded from its realm +and used. + +``` + +Class containerClass = containerRealm.loadClass( CONTAINER_CLASSNAME ); +MyContainer container = (MyContainer) containerClass.newInstance(); +Thread.currentThread().setContextClassLoader( containerRealm.getClassLoader() ); +container.run(); + +``` + +Ideally, the container itself would be responsible for creating +a `ClassRealm` for each component that's loaded, and +importing the component contract interfaces into the component's +`ClassRealm` and using `loadClass(..)` +to gain entry into the sandboxed component realm. diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md new file mode 100644 index 00000000..54777814 --- /dev/null +++ b/src/site/markdown/index.md @@ -0,0 +1,53 @@ +--- +title: Plexus Classworlds +author: bob mcwhirter +--- + +# Overview + +**Plexus Classworlds** is a framework for container developers +who require complex manipulation of Java's ClassLoaders. Java's +native ClassLoader mechanisms and classes can cause +much headache and confusion for certain types of application +developers. Projects which involve dynamic loading of components +or otherwise represent a 'container' can benefit from the classloading +control provided by **Classworlds**. + +**Plexus Classworlds** provides a richer set of semantics for +class loading than Java's normal mechanisms, while still being +able to provide a ClassLoader interface to integrate +seamlessly with the Java environment. + +The **Classworlds** model does away with the hierarchy +normally associated with ClassLoaders. Instead, +[`ClassWorld`](apidocs/index.html?org/codehaus/plexus/classworlds/ClassWorld.html) provides a +pool of [`ClassRealms`](apidocs/index.html?org/codehaus/plexus/classworlds/realm/ClassRealm.html) +which can import arbitrary packages from other ClassRealms. +Effectively, **Classworlds** turns the old-style +hierarchy into a directed graph. + +In a application container environment, the container may +have a realm capable of loading on the container/component +contract interfaces and classes. Another realm is created +for each component which imports the contract classes from +the container realm. + +This model allows for fine-grained control of which +classloader loads any particular class. This form of +partial isolation can reduce the myriad strange errors +that are produced by loading classes from multiple +loaders. + +In addition, **Plexus Classworlds** provides a +[launcher](launcher.html) +to assist in the creation of classloaders and `ClassRealm`s +from a configuration file and the launching of the application's `main` +method from the correct class loaded through the correct classloader. + +And for seamless transition from [older **Classworlds** up to 1.1](https://github.com/codehaus/classworlds), +**Plexus Classworlds** provides +[a compatibility layer](apidocs/index.html?org/codehaus/classworlds/package-summary.html). +This package is deprecated for new code but must remain on the classpath because +`org.eclipse.sisu:org.eclipse.sisu.plexus` references it in its compiled bytecode. +See [COMPATIBILITY.md](https://github.com/codehaus-plexus/plexus-classworlds/blob/master/COMPATIBILITY.md) +for details. diff --git a/src/site/markdown/launcher.md b/src/site/markdown/launcher.md new file mode 100644 index 00000000..94f75a3a --- /dev/null +++ b/src/site/markdown/launcher.md @@ -0,0 +1,148 @@ +--- +title: App Launching +author: bob mcwhirter +--- + +# Launcher Introduction + +## Purpose + +In order to reduce the number of classloading projects, +**Plexus 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](apidocs/index.html?org/codehaus/plexus/classworlds/launcher/package-summary.html) +of **Classworlds** simplify +the process of locating application jars. A common idiom is +to have a script which starts the JVM with only the +`plexus-classworlds.jar` in the classpath and a system +property to specify the location of a launcher configuration. +Additionally, typically a property specifying the application installation +location is passed on the command-line. + +``` + +$JAVA_HOME/bin/java \ + -classpath $APP_HOME/boot/plexus-classworlds-2.5.2.jar \ + -Dclassworlds.conf=$APP_HOME/etc/classworlds.conf \ + -Dapp.home=$APP_HOME \ + org.codehaus.plexus.classworlds.launcher.Launcher \ + $* + +``` + +# Configuration + +## Entry Point 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 + +``` + +## System Properties Definition + +System properties can be set before and after the entry point, but before realms: + +``` + +set [[using ]] [[default ]] + +``` + +## 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, three directives are available: +`load`, `optionally` and `import`. + +The `load` and `optionally` +directives specify a class source to be used for loading +classes in the realm: the only difference is that in case of absent source, +`load` fails but `optionally` does not. +Any loaded source that contain a star (`*`) in the file name is +replaced by the list of files that match the filename prefix and suffix. +System properties may be referred to using `${propname}` notation. +The `load` and `optionally` directives are equivalent to the +`addURL(..)` method of `ClassRealm`. + +``` + +[app] + load ${app.home}/lib/*.jar + optionally ${app.home}/lib/ext/*.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 equivalent +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 +provided. Simply add a `ClassWorld` parameter to +the standard `main` parameter list. + +``` + +public class MyApp +{ + public static void main( String[] args, ClassWorld world ) + { + ... + } +} + +``` diff --git a/src/site/xdoc/apiusage.xml b/src/site/xdoc/apiusage.xml deleted file mode 100644 index 30793c27..00000000 --- a/src/site/xdoc/apiusage.xml +++ /dev/null @@ -1,93 +0,0 @@ - - - - - - Classworlds API Usage - bob mcwhirter - - - - -
- -

- The Java API can be used to create new realms and connect - realms together through importation of specific packages. -

- -

- The core of the Classworlds infrastructure is - the - ClassWorld - class. An application must create a ClassWorld instance. - It is advisable to store the instance as a singleton or some other - handy location. -

- - - -

- Once a ClassWorld is created, realms within it - can be created. These realms effectively only allow loading - of the core JVM classes initially. -

- - - -

- In order to make each ClassRealm useful, constituents - in form of URLs must be added to it where each can provide certain classes. - The URL must return either a JAR or a directory on the default file system. -

- - - -

- ClassRealms can optionally be filtered to further restrict which classes/resources - are exposed. The filter is provided as additional argument to world.newRealm( "filteredcontainer", myPredicate ); -

- -

- Now, links between the various realms need to be created to allow - classes loaded from one to be available to classes loaded in another. -

- - - -

- The container implementation can then be loaded from its realm - and used. -

- - - -

- Ideally, the container itself would be responsible for creating - a ClassRealm for each component that's loaded, and - importing the component contract interfaces into the component's - ClassRealm and using loadClass(..) - to gain entry into the sandboxed component realm. -

- -
- - - \ No newline at end of file diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml deleted file mode 100644 index 8a5fe095..00000000 --- a/src/site/xdoc/index.xml +++ /dev/null @@ -1,78 +0,0 @@ - - - - - - Plexus Classworlds - bob mcwhirter - - - - -
- -

- Plexus Classworlds is a framework for container developers - who require complex manipulation of Java's ClassLoaders. Java's - native ClassLoader mechanisms and classes can cause - much headache and confusion for certain types of application - developers. Projects which involve dynamic loading of components - or otherwise represent a 'container' can benefit from the classloading - control provided by Classworlds. -

- -

- Plexus Classworlds provides a richer set of semantics for - class loading than Java's normal mechanisms, while still being - able to provide a ClassLoader interface to integrate - seamlessly with the Java environment. -

- -

- The Classworlds model does away with the hierarchy - normally associated with ClassLoaders. Instead, - ClassWorld provides a - pool of ClassRealms - which can import arbitrary packages from other ClassRealms. - Effectively, Classworlds turns the old-style - hierarchy into a directed graph. -

- -

- In a application container environment, the container may - have a realm capable of loading on the container/component - contract interfaces and classes. Another realm is created - for each component which imports the contract classes from - the container realm. -

- -

- This model allows for fine-grained control of which - classloader loads any particular class. This form of - partial isolation can reduce the myriad strange errors - that are produced by loading classes from multiple - loaders. -

- -

- In addition, Plexus Classworlds provides a - launcher - to assist in the creation of classloaders and ClassRealms - from a configuration file and the launching of the application's main - method from the correct class loaded through the correct classloader. -

- -

- And for seamless transition from older Classworlds up to 1.1, - Plexus Classworlds provides - a compatibility layer. - This package is deprecated for new code but must remain on the classpath because - org.eclipse.sisu:org.eclipse.sisu.plexus references it in its compiled bytecode. - See COMPATIBILITY.md - for details. -

-
- - - - diff --git a/src/site/xdoc/launcher.xml b/src/site/xdoc/launcher.xml deleted file mode 100644 index 67273983..00000000 --- a/src/site/xdoc/launcher.xml +++ /dev/null @@ -1,180 +0,0 @@ - - - - - - App Launching - bob mcwhirter - - - - -
- - - -

- In order to reduce the number of classloading projects, - Plexus 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 - plexus-classworlds.jar in the classpath and a system - property to specify the location of a launcher configuration. - Additionally, typically a property specifying the application installation - location is passed on the command-line. -

- - - - - -
- -
- - - -

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

- - - - - - - -

- System properties can be set before and after the entry point, but before realms: -

- - [[using ]] [[default ]] -]]> - - - - - -

- 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. -

- - - -

- Within a realm definition, three directives are available: - load, optionally and import. -

- -

- The load and optionally - directives specify a class source to be used for loading - classes in the realm: the only difference is that in case of absent source, - load fails but optionally does not. - Any loaded source that contain a star (*) in the file name is - replaced by the list of files that match the filename prefix and suffix. - System properties may be referred to using ${propname} notation. - The load and optionally directives are equivalent to the - addURL(..) method of ClassRealm. -

- - - -

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

- - - - - - - -

- 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 - provided. Simply add a ClassWorld parameter to - the standard main parameter list. -

- - - - - -
- - - - \ No newline at end of file