Skip to content

PROTOCOLS.md

Latest commit

 

History

History
528 lines (433 loc) · 13.6 KB

PROTOCOLS.md

File metadata and controls

528 lines (433 loc) · 13.6 KB

JClassLoader Protocol Support

⚠️ DEPRECATED DOCUMENTATION: This file contains legacy examples from version 1.0.

For current documentation, see:

Version 1.1+ Changes:

  • File transfer protocols (SFTP, WebDAV, SMB/CIFS, FTP/FTPS) moved to jfiletransfer
  • Messaging systems (Kafka, RabbitMQ, Redis) moved to jmessaging
  • Container systems (Kubernetes, Docker, Hazelcast) moved to jcontainer
  • Version control (Git) moved to jvcs
  • Use adapter classes: FileTransferClassSource, MessageClientClassSource, ContainerClientClassSource, VcsClientClassSource

Legacy Documentation (Version 1.0)

Comprehensive guide to all supported protocols and storage systems.

Table of Contents

  1. Local & Network File Systems
  2. Cloud Object Storage
  3. Cloud File Storage
  4. Repository Systems
  5. REST APIs & Custom Protocols
  6. Database Storage

Local & Network File Systems

Local File System

JClassLoader loader = JClassLoader.builder()
    .addLocalSource("/opt/app/classes")
    .build();

HTTP/HTTPS

// Public HTTP server
JClassLoader loader = JClassLoader.builder()
    .addRemoteSource("https://cdn.example.com/classes/")
    .build();

// With authentication
JClassLoader authLoader = JClassLoader.builder()
    .addRemoteSource("https://secure.example.com/classes/",
                    AuthConfig.basic("user", "password"))
    .build();

FTP/FTPS

// Anonymous FTP
FtpClassSource ftp = new FtpClassSource("ftp://ftp.example.com/classes/");

// Authenticated FTPS
FtpClassSource ftps = new FtpClassSource(
    "ftps://secure.example.com/classes/",
    "username", "password"
);

JClassLoader loader = JClassLoader.builder()
    .addClassSource(ftp)
    .build();

SFTP (SSH File Transfer Protocol)

// Password authentication
SftpClassSource sftp = SftpClassSource.builder()
    .host("sftp.example.com")
    .port(22)
    .username("deploy-user")
    .password("secret")
    .basePath("/var/classes")
    .build();

// Private key authentication
SftpClassSource sftpKey = SftpClassSource.builder()
    .host("secure.example.com")
    .username("deploy-user")
    .privateKey("/home/user/.ssh/id_rsa")
    .basePath("/opt/classes")
    .build();

JClassLoader loader = JClassLoader.builder()
    .addClassSource(sftp)
    .build();

WebDAV

// Public WebDAV
JClassLoader loader = JClassLoader.builder()
    .addWebDavSource("https://dav.example.com/classes/")
    .build();

// Authenticated WebDAV
JClassLoader authLoader = JClassLoader.builder()
    .addWebDavSource("https://secure-dav.example.com/",
                    "username", "password")
    .build();

Cloud Object Storage

AWS S3

// With explicit credentials
S3ClassSource s3 = S3ClassSource.builder()
    .region(Region.US_EAST_1)
    .bucket("my-classes-bucket")
    .prefix("production/classes")
    .credentials("ACCESS_KEY_ID", "SECRET_ACCESS_KEY")
    .build();

// Using IAM roles / default credentials
S3ClassSource s3Auto = S3ClassSource.builder()
    .region("us-west-2")
    .bucket("company-classes")
    .prefix("releases/v1.0")
    .build();

JClassLoader loader = JClassLoader.builder()
    .addS3Source(s3)
    .build();

Azure Blob Storage

// With connection string
AzureBlobClassSource azure = AzureBlobClassSource.builder()
    .connectionString("DefaultEndpointsProtocol=https;AccountName=...")
    .container("classes-container")
    .prefix("prod/classes")
    .build();

// With account credentials
AzureBlobClassSource azureKey = AzureBlobClassSource.builder()
    .accountName("mycompanystorage")
    .accountKey("account-key-here")
    .container("application-classes")
    .build();

JClassLoader loader = JClassLoader.builder()
    .addAzureBlobSource(azure)
    .build();

Google Cloud Storage

// With project ID
GcsClassSource gcs = GcsClassSource.builder()
    .projectId("my-gcp-project")
    .bucket("company-classes-bucket")
    .prefix("releases/production")
    .build();

// Using default credentials
GcsClassSource gcsAuto = GcsClassSource.builder()
    .bucket("app-classes")
    .build();

JClassLoader loader = JClassLoader.builder()
    .addGcsSource(gcs)
    .build();

Cloud File Storage

Google Drive

// From service account credentials file
GoogleDriveClassSource drive = GoogleDriveClassSource.builder()
    .credentialsFromStream(new FileInputStream("credentials.json"))
    .folderId("1234567890abcdefg")  // Optional: specific folder
    .applicationName("MyApp")
    .build();

JClassLoader loader = JClassLoader.builder()
    .addGoogleDriveSource(drive)
    .build();

Dropbox

DropboxClassSource dropbox = DropboxClassSource.builder()
    .accessToken("your-dropbox-access-token")
    .basePath("/Apps/ClassLoader/classes")
    .build();

JClassLoader loader = JClassLoader.builder()
    .addDropboxSource(dropbox)
    .build();

Microsoft OneDrive

// Requires Microsoft Graph API setup
GraphServiceClient<?> graphClient = ... // Configure with OAuth
OneDriveClassSource oneDrive = OneDriveClassSource.builder()
    .graphClient(graphClient)
    .basePath("ClassLoader/classes")
    .build();

JClassLoader loader = JClassLoader.builder()
    .addOneDriveSource(oneDrive)
    .build();

Repository Systems

Maven Central

JClassLoader loader = JClassLoader.builder()
    .addMavenCentral(
        "org.apache.commons:commons-lang3:3.12.0",
        "com.google.guava:guava:32.1.0-jre"
    )
    .build();

Generic Maven Repository

// JFrog Artifactory, Apache Archiva, etc.
MavenRepositoryClassSource maven = MavenRepositoryClassSource.builder()
    .repositoryUrl("https://maven.example.com/repository/")
    .addArtifact("org.example:my-lib:1.0.0")
    .auth(AuthConfig.basic("maven-user", "maven-password"))
    .build();

JClassLoader loader = JClassLoader.builder()
    .addClassSource(maven)
    .build();

Sonatype Nexus

Nexus Raw Repository

JClassLoader loader = JClassLoader.builder()
    .addNexusRawSource("https://nexus.example.com", "raw-classes")
    .build();

Nexus Maven Repository

MavenNexusClassSource nexus = MavenNexusClassSource.builder()
    .nexusUrl("https://nexus.example.com")
    .repository("maven-releases")
    .addArtifact("com.company:internal-lib:1.0.0")
    .auth(AuthConfig.basic("user", "password"))
    .build();

JClassLoader loader = JClassLoader.builder()
    .addNexusMavenSource(nexus)
    .build();

REST APIs & Custom Protocols

Generic REST API

RestApiClassSource rest = RestApiClassSource.builder()
    .baseUrl("https://api.example.com/classes")
    .classPathTemplate("v1/download/{fullclass}")
    .addHeader("X-API-Version", "2.0")
    .addHeader("Accept", "application/octet-stream")
    .addQueryParam("format", "binary")
    .auth(AuthConfig.bearer("api-token-12345"))
    .responseFormat(RestApiClassSource.ResponseFormat.BINARY)
    .build();

JClassLoader loader = JClassLoader.builder()
    .addRestApiSource(rest)
    .build();

Template Variables:

  • {package} - Package path (e.g., com/example)
  • {class} - Simple class name (e.g., MyClass)
  • {fullclass} - Full class path (e.g., com/example/MyClass)

Response Formats:

  • BINARY - Raw class file bytes
  • BASE64_JSON_FIELD - Base64-encoded in JSON field named "data" or "content"
  • DIRECT - Direct response

Custom Protocol Handler

// Implement your own protocol
public class CustomProtocol implements ProtocolHandler {
    @Override
    public byte[] fetchClass(String className) throws IOException {
        // Your custom logic
    }

    @Override
    public boolean canHandle(String className) {
        // Check if this handler can load the class
    }

    @Override
    public String getProtocolName() {
        return "custom";
    }

    @Override
    public void close() throws IOException {
        // Cleanup
    }
}

CustomProtocolClassSource custom = new CustomProtocolClassSource(
    new CustomProtocol()
);

JClassLoader loader = JClassLoader.builder()
    .addClassSource(custom)
    .build();

Database Storage

JDBC Database

// Classes stored as BLOBs in database
DataSource dataSource = ... // Configure your database

JClassLoader loader = JClassLoader.builder()
    .addDatabaseSource(
        dataSource,
        "class_storage",      // Table name
        "class_name",         // Class name column
        "class_bytes"         // Class bytes (BLOB) column
    )
    .build();

Database Schema Example:

CREATE TABLE class_storage (
    class_name VARCHAR(255) PRIMARY KEY,
    class_bytes BLOB NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO class_storage (class_name, class_bytes)
VALUES ('com.example.MyClass', <binary class data>);

Multi-Protocol Enterprise Example

import org.flossware.jclassloader.*;
import org.flossware.jclassloader.cache.FileSystemCache;
import org.flossware.jclassloader.cloud.*;

// Enterprise setup with comprehensive fallbacks
JClassLoader enterpriseLoader = JClassLoader.builder()
    // 1. Local development overrides
    .addLocalSource("/opt/app/dev-overrides")

    // 2. Primary cloud storage (AWS S3)
    .addS3Source(S3ClassSource.builder()
        .region(Region.US_EAST_1)
        .bucket("prod-classes")
        .prefix("v3/classes")
        .build())

    // 3. Backup cloud (Azure)
    .addAzureBlobSource(AzureBlobClassSource.builder()
        .accountName("backup-storage")
        .accountKey("key")
        .container("classes-dr")
        .build())

    // 4. Shared team resources (Google Drive)
    .addGoogleDriveSource(googleDriveSource)

    // 5. Network file server (SFTP)
    .addClassSource(SftpClassSource.builder()
        .host("team-server.com")
        .username("build-agent")
        .privateKey("/var/secrets/key")
        .basePath("/shared/classes")
        .build())

    // 6. Internal Maven artifacts
    .addMavenRepository("https://maven.company.com/internal/",
        "com.company:core:3.1.0",
        "com.company:api-client:2.5.0")

    // 7. Maven Central (open source dependencies)
    .addMavenCentral(
        "org.apache.commons:commons-lang3:3.12.0",
        "com.google.code.gson:gson:2.10.1")

    // 8. Legacy REST API
    .addRestApiSource(restApiSource)

    // 9. Database fallback
    .addDatabaseSource(dataSource, "class_storage",
                      "class_name", "class_bytes")

    // Enable caching for performance
    .cache(new FileSystemCache("/var/cache/jclassloader"))
    .useCache(true)
    .build();

Performance & Caching

All protocols support optional caching:

import org.flossware.jclassloader.cache.FileSystemCache;

FileSystemCache cache = new FileSystemCache("/tmp/class-cache");

JClassLoader loader = JClassLoader.builder()
    .addS3Source(s3Source)
    .addMavenCentral("org.example:lib:1.0.0")
    .cache(cache)
    .useCache(true)
    .build();

Benefits:

  • Reduces network requests
  • Improves class loading performance
  • Offline capability after initial load
  • Reduces cloud storage costs

Authentication Summary

Protocol Auth Methods
HTTP/HTTPS Basic, Bearer Token
FTP/FTPS Username/Password
SFTP Password, Private Key
WebDAV Username/Password
AWS S3 Access Keys, IAM Roles
Azure Blob Account Key, Connection String
Google Cloud Storage Service Account, Default Credentials
Google Drive OAuth, Service Account
Dropbox Access Token
OneDrive Microsoft Graph OAuth
Maven Repos Basic, Bearer Token
Nexus Basic, Bearer Token
REST API Basic, Bearer Token, Custom Headers
Database JDBC Connection

Protocol Selection Guide

Use Case Recommended Protocols
Production deployment AWS S3, Azure Blob, GCS
Team collaboration Google Drive, Dropbox, OneDrive, SFTP
CI/CD pipelines Maven (Central/Nexus), S3, Azure
Legacy systems FTP, Database, REST API
Enterprise networks SFTP, WebDAV, Internal Maven
Development Local, HTTP, Maven Central
Disaster recovery Multiple cloud providers
Air-gapped environments Local, Database, Internal network

Complete Protocol List (30 implementations)

  1. ✅ Local File System
  2. ✅ HTTP
  3. ✅ HTTPS
  4. ✅ FTP
  5. ✅ FTPS
  6. ✅ SFTP
  7. ✅ WebDAV
  8. ✅ AWS S3
  9. ✅ Azure Blob Storage
  10. ✅ Google Cloud Storage
  11. ✅ Google Drive
  12. ✅ Dropbox
  13. ✅ Microsoft OneDrive
  14. ✅ Maven Central
  15. ✅ Generic Maven Repository
  16. ✅ Nexus Raw Repository
  17. ✅ Nexus Maven Repository
  18. ✅ REST API (Binary)
  19. ✅ REST API (JSON/Base64)
  20. ✅ JDBC Database
  21. ✅ Custom Protocol Handler
  22. ✅ JFrog Artifactory (via Maven)
  23. ✅ Apache Archiva (via Maven)
  24. ✅ GitHub Packages (via Maven)
  25. ✅ GitLab Package Registry (via Maven)
  26. ✅ JCenter (via Maven)
  27. ✅ Google Maven (via Maven)
  28. ✅ File-based caching
  29. ✅ Authentication (7 methods)
  30. ✅ Custom protocol handlers

Total Source Files: 30 Java classes Total Tests: 26+ unit tests All Tests: ✅ PASSING