From 5fbc649721c9032fa8424cab2a0b8590486f54d5 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Sat, 8 Aug 2026 21:04:25 +0200 Subject: [PATCH] Rewrite README with usage, status and version guidance Adds what the library does - realms as a directed graph rather than a hierarchy, which is how Maven isolates plugins - plus the launcher, a dependency snippet, the Java baseline and documentation links. The Backward Compatibility section is kept verbatim. It is the most valuable documentation in the organisation: it records why the legacy org.codehaus.classworlds package cannot be removed, which Sisu bytecode references it, and the PR that tried and had to be reverted. The skeleton is built around it rather than over it. Drops the 2015 'current master is now at' line. Part of codehaus-plexus/.github#58 --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 49 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1f8c866a..e2b71ed8 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,42 @@ -Plexus-Classworlds -================== +# Plexus Classworlds -[![Apache License, Version 2.0, January 2004](https://img.shields.io/github/license/codehaus-plexus/plexus-classworlds.svg?label=License)](http://www.apache.org/licenses/) -[![Maven Central](https://img.shields.io/maven-central/v/org.codehaus.plexus/plexus-classworlds.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.codehaus.plexus/plexus-classworlds) +[![Maven Central](https://img.shields.io/maven-central/v/org.codehaus.plexus/plexus-classworlds.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.codehaus.plexus/plexus-classworlds) +[![GitHub CI](https://github.com/codehaus-plexus/plexus-classworlds/workflows/GitHub%20CI/badge.svg)](https://github.com/codehaus-plexus/plexus-classworlds/actions) [![Reproducible Builds](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/org/codehaus/plexus/plexus-classworlds/badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/codehaus/plexus/plexus-classworlds/README.md) -![Build Status](https://github.com/codehaus-plexus/plexus-classworlds/workflows/GitHub%20CI/badge.svg) +[![License](https://img.shields.io/github/license/codehaus-plexus/plexus-classworlds.svg?label=License)](https://www.apache.org/licenses/LICENSE-2.0) -Current master is now at https://github.com/codehaus-plexus/plexus-classworlds +A classloader framework for container developers who need more than Java's built-in hierarchy. -Backward Compatibility ----------------------- +Classworlds replaces the strict parent-child classloader tree with a pool of **realms** that can import +specific packages from each other — a directed graph rather than a hierarchy. That is how Maven keeps a +plugin's dependencies from colliding with its own, and how it loads plugins in isolation from one another. + +It also ships a [launcher](https://codehaus-plexus.github.io/plexus-classworlds/launcher.html) that builds +the realms from a configuration file and invokes an application's `main` method in the right one. Maven's +own startup scripts use it. + +## Status + +Maintained, conservatively. Maven's startup depends on this, so changes are deliberate and public API is +kept compatible. + +## Using it + +```xml + + org.codehaus.plexus + plexus-classworlds + 2.12.0 + +``` + +Check the badge above for the current version. + +## Requirements + +Java 8 or later. + +## Backward Compatibility This project maintains a legacy compatibility layer in the `org.codehaus.classworlds` package. This package **cannot be removed** without coordinating with the Eclipse Sisu and Apache Maven teams. @@ -24,3 +51,17 @@ PR #141 removed this package and had to be reverted immediately (see commit 2234 New code should use the `org.codehaus.plexus.classworlds` package. See [COMPATIBILITY.md](COMPATIBILITY.md) for the full picture, including what Sisu references and what is required before any future removal can be considered. + +## Documentation + +- [Project site](https://codehaus-plexus.github.io/plexus-classworlds/) — including [API usage](https://codehaus-plexus.github.io/plexus-classworlds/apiusage.html) and the [launcher](https://codehaus-plexus.github.io/plexus-classworlds/launcher.html) +- [Javadoc](https://javadoc.io/doc/org.codehaus.plexus/plexus-classworlds) +- [Release notes](https://github.com/codehaus-plexus/plexus-classworlds/releases) + +## Contributing + +See [CONTRIBUTING.md](https://github.com/codehaus-plexus/.github/blob/master/CONTRIBUTING.md). In short: +`mvn verify` builds, and run `mvn spotless:apply` before pushing or CI will fail on formatting. + +Please report security vulnerabilities privately — see +[SECURITY.md](https://github.com/codehaus-plexus/.github/blob/master/SECURITY.md), not a public issue.