Skip to content

README.md

Latest commit

 

History

History
197 lines (142 loc) · 5.58 KB

README.md

File metadata and controls

197 lines (142 loc) · 5.58 KB
Raw

classloader-java

A Java ClassLoader that loads classes from local directories, HTTP/HTTPS servers, Maven repositories, databases, object stores, and more. Supports caching, authentication, bytecode verification, configurable delegation, and lifecycle listeners.

Java 11+ | GPLv3 | Maven Central: org.flossware:classloader-java:2.0

Quick Start

<dependency>
    <groupId>org.flossware</groupId>
    <artifactId>classloader-java</artifactId>
    <version>2.0</version>
</dependency>
try (ApplicationClassLoader loader = ApplicationClassLoader.builder()
        .addLocalSource("/opt/app/classes")
        .addRemoteSource("https://cdn.example.com/classes")
        .addMavenCentral("com.google.guava:guava:32.1.0-jre")
        .build()) {
    Class<?> clazz = loader.loadClass("com.example.MyClass");
}

Class Sources

Source Class Use Case
Local filesystem LocalClassSource Load .class files from a directory
HTTP/HTTPS RemoteClassSource Download classes from a web server
Remote JAR RemoteJarClassSource Download and extract a JAR
Maven repository MavenRepositoryClassSource Load from Maven Central or private repos
Nexus repository NexusClassSource Load from Sonatype Nexus (RAW or Maven)
JDBC database DatabaseClassSource Load bytecode stored in a database table
REST API RestApiClassSource Load from a custom REST endpoint
MinIO / S3 MinioClassSource Load from S3-compatible object storage
HDFS HdfsClassSource Load from Hadoop Distributed File System
Custom protocol CustomProtocolClassSource Load via registered protocol handlers
Custom Implement ClassSource Any source you need

Extension Sources (optional)

These require the FlossWare extension libraries. Build with -Pflossware-extensions when these artifacts are in your local Maven repository.

Source Class Dependency
Cloud storage CloudStorageClassSource org.flossware:cloudstorage-java
File transfer (SFTP/FTP) FileTransferClassSource org.flossware:filetransfer-java
Message queue MessageClientClassSource org.flossware:messaging-java
Container registry ContainerClientClassSource org.flossware:container-java
VCS (Git) VcsClientClassSource org.flossware:vcs-java

Builder Shortcuts

ApplicationClassLoader loader = ApplicationClassLoader.builder()
    // Local
    .addLocalSource("/path/to/classes")

    // Remote with auth
    .addRemoteSource("https://secure.example.com/classes",
        AuthConfig.bearer("my-token"))

    // Remote JAR
    .addRemoteJar("https://cdn.example.com/lib-1.0.jar")

    // Maven Central
    .addMavenCentral("org.apache.commons:commons-lang3:3.12.0")

    // Custom Maven repo
    .addMavenRepository("https://nexus.example.com/repository/releases/",
        "com.internal:my-lib:2.0")

    // Nexus RAW
    .addNexusRawSource("https://nexus.example.com", "my-repo",
        AuthConfig.basic("user", "pass"))

    // Database
    .addDatabaseSource(dataSource, "class_files", "class_name", "bytecode")

    // Any ClassSource implementation
    .addClassSource(myCustomSource)

    .build();

MinIO / S3

MinioClassSource source = MinioClassSource.builder()
    .endpoint("minio.example.com")
    .accessKey("minioadmin")
    .secretKey("minioadmin")
    .bucket("classes")
    .prefix("production/v2")
    .build();

Works with any S3-compatible service (AWS S3, Backblaze B2, Cloudflare R2, DigitalOcean Spaces).

Delegation Strategies

Controls whether the parent ClassLoader or custom sources are checked first.

// Standard Java behavior (default)
builder.parentFirst()

// Check custom sources first (for class isolation / overriding)
builder.parentLast()

// Per-class control
builder.customDelegation(className ->
    className.startsWith("com.example.shared."))

parentLast() always delegates java.*, javax.*, sun.*, and jdk.* to the parent.

Caching

Caching is enabled by default (in-memory). Use FileSystemCache for persistence across JVM restarts:

builder.cache(new FileSystemCache(Paths.get("/tmp/class-cache")))

Disable caching:

builder.useCache(false)

Bytecode Verification

Validate loaded classes against known checksums:

Map<String, String> checksums = Map.of(
    "com.example.MyClass", "sha256:abc123..."
);
builder.bytecodeVerifier(new ChecksumValidator(checksums))

Lifecycle Listeners

Monitor class loading events:

builder.addLoggingListener(true)   // Log load, cache, resource events
       .trackResources()           // Track loaded classes and bytes

// Custom listener
builder.addListener(new ClassLoaderLifecycleListener() {
    @Override
    public void onClassLoaded(ClassLoadEvent event) { /* ... */ }
})

Authentication

AuthConfig.none()                          // No auth
AuthConfig.basic("username", "password")   // HTTP Basic
AuthConfig.bearer("token")                 // Bearer token

Thread Safety

ApplicationClassLoader is thread-safe. It uses a ReentrantReadWriteLock (fair) to protect findClass() and findResource(), and prevents class loading after close().

API Documentation

Generate Javadoc:

mvn javadoc:javadoc

Output: target/site/apidocs/index.html

Building

mvn clean install

Optional FlossWare extensions (cloud storage, file transfer, messaging, container, VCS):

mvn clean install -Pflossware-extensions

License

GNU General Public License v3.0