From 0856cdc91e2f973a6d711fa44733464a2d272063 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Sat, 8 Aug 2026 19:17:41 +0200 Subject: [PATCH 1/4] Rename the site documents ahead of converting them Git records a rename plus a rewrite in one commit as a delete and an add, which stops 'git log --follow'. Splitting the rename out keeps the history. Please merge or rebase rather than squash. --- src/site/{xdoc/apiusage.xml => markdown/apiusage.md} | 0 src/site/{xdoc/index.xml => markdown/index.md} | 0 src/site/{xdoc/launcher.xml => markdown/launcher.md} | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename src/site/{xdoc/apiusage.xml => markdown/apiusage.md} (100%) rename src/site/{xdoc/index.xml => markdown/index.md} (100%) rename src/site/{xdoc/launcher.xml => markdown/launcher.md} (100%) diff --git a/src/site/xdoc/apiusage.xml b/src/site/markdown/apiusage.md similarity index 100% rename from src/site/xdoc/apiusage.xml rename to src/site/markdown/apiusage.md diff --git a/src/site/xdoc/index.xml b/src/site/markdown/index.md similarity index 100% rename from src/site/xdoc/index.xml rename to src/site/markdown/index.md diff --git a/src/site/xdoc/launcher.xml b/src/site/markdown/launcher.md similarity index 100% rename from src/site/xdoc/launcher.xml rename to src/site/markdown/launcher.md From 0a6d09cb3ec3e2bc88cc645d463dba0c7ef8eac2 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Sat, 8 Aug 2026 19:22:14 +0200 Subject: [PATCH 2/4] Convert the site documents from xdoc to Markdown Converted with doxia-converter, then cleaned up. The 1.3 converter has three defects that are invisible in the Markdown and only appear in the generated HTML: it emits the front matter without its --- fences, it shifts every heading down one level, and it keeps the source XML indentation, which turns prose into indented code blocks. Also excludes site sources from the Spotless markdown formatter. This is not optional: flexmark rewrites the fence closing a front matter block into a setext underline, which destroys the title and author. It happened during this conversion - the first build silently emptied all three pages. The released parent POM 25 does not carry this exclusion, and spotless.action defaults to apply outside CI. Verified by building the site before and after and diffing the normalised pages. Title, author, visible text and link targets are identical on all three. Part of codehaus-plexus/.github#58 --- pom.xml | 20 ++++ src/site/markdown/apiusage.md | 117 +++++++++----------- src/site/markdown/index.md | 131 +++++++++------------- src/site/markdown/launcher.md | 202 ++++++++++++++-------------------- 4 files changed, 208 insertions(+), 262 deletions(-) diff --git a/pom.xml b/pom.xml index 966e0760..39067fe6 100644 --- a/pom.xml +++ b/pom.xml @@ -85,6 +85,26 @@ + + com.diffplug.spotless + spotless-maven-plugin + + + + **/*.md + + + target/** + + **/src/site/markdown/** + + + + + org.apache.maven.plugins maven-scm-publish-plugin diff --git a/src/site/markdown/apiusage.md b/src/site/markdown/apiusage.md index 30793c27..6cfbacc1 100644 --- a/src/site/markdown/apiusage.md +++ b/src/site/markdown/apiusage.md @@ -1,93 +1,76 @@ - +--- +title: Classworlds API Usage +author: bob mcwhirter +--- - +# Classworlds API Usage - - 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](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. -
+``` -

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

+ClassWorld world = new ClassWorld(); -

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

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

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

+``` + +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 +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 index 8a5fe095..54777814 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -1,78 +1,53 @@ - - - - - - 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. -

-
- - - - +--- +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 index 67273983..94f75a3a 100644 --- a/src/site/markdown/launcher.md +++ b/src/site/markdown/launcher.md @@ -1,95 +1,76 @@ - +--- +title: App Launching +author: bob mcwhirter +--- - +# Launcher Introduction - - App Launching - bob mcwhirter - +## 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. -

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

- - - +``` -
+# Configuration -
+## Entry Point Definition - +The entry-point class and realm must be specified +using the `main is` directive before +specifying realm definitions. -

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

+``` - - +``` - +## System Properties Definition -

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

+System properties can be set before and after the entry point, but before realms: + +``` - [[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. -

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

+``` - [[using ]] [[default ]] [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. -

- - -

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

+``` + +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`. + +``` - - +``` + +## 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. -

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

- 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 +``` From 16917eaf0217327a1232b3b4a02eb043d433aed7 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Sat, 8 Aug 2026 19:45:24 +0200 Subject: [PATCH 3/4] Move the Spotless exclusion to pluginManagement Declaring the plugin in build/plugins forced it to run on every JDK. The parent only declares Spotless inside its java17+ profile, because Spotless 3.x is compiled for Java 17, so the JDK 8 CI jobs failed with 'has been compiled by a more recent version of the Java Runtime'. pluginManagement configures the plugin without declaring it, so the exclusion applies wherever the parent activates Spotless and JDK 8 builds are untouched. --- pom.xml | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/pom.xml b/pom.xml index 39067fe6..4ddd351c 100644 --- a/pom.xml +++ b/pom.xml @@ -82,29 +82,29 @@ + + com.diffplug.spotless + spotless-maven-plugin + + + + **/*.md + + + target/** + + **/src/site/markdown/** + + + + + - - com.diffplug.spotless - spotless-maven-plugin - - - - **/*.md - - - target/** - - **/src/site/markdown/** - - - - - org.apache.maven.plugins maven-scm-publish-plugin From 02d8c3cc2c18be327f961c01d2cb4a49601c0639 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Sat, 8 Aug 2026 20:39:50 +0200 Subject: [PATCH 4/4] Drop the local Spotless exclusion, now carried by the parent Parent 26 excludes src/site/markdown from the Markdown formatter, so the override added here is redundant. Removing the whole spotless entry rather than just the one exclude line: plugin configuration does not merge list elements, so a local holding only target/** would replace the parent's list and quietly take the site exclusion with it. --- pom.xml | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/pom.xml b/pom.xml index 4ddd351c..966e0760 100644 --- a/pom.xml +++ b/pom.xml @@ -82,26 +82,6 @@ - - com.diffplug.spotless - spotless-maven-plugin - - - - **/*.md - - - target/** - - **/src/site/markdown/** - - - - -