Convert the site documents from xdoc to Markdown

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.

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.

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 <property> [[using <properties filename>]] [[default <default value>]]
+
+```
+
+## 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 )
+    {
+        ...     
+    }
+}
+
+```