Skip to content
Plugwerk

General Information

The Plugwerk Client Plugin is a PF4J plugin that acts as a bridge between your host application and one or more Plugwerk Servers. It provides a simple, unified API for discovering, installing, and updating plugins at runtime — without your application needing to know the details of the Plugwerk REST API.

How It Works

Section titled “How It Works”

The client plugin is packaged as a PF4J ZIP bundle and loaded at runtime by your application's PluginManager. Once loaded, it registers SPI extension points that your application can use to interact with the Plugwerk Server:

| Extension Point | Purpose | | ----------------------- | ------------------------------------- | | PlugwerkCatalog | Browse and search the plugin catalog | | PlugwerkInstaller | Download, verify, install (load + start), and uninstall plugins | | PlugwerkUpdateChecker | Check installed plugins for updates | | PlugwerkMarketplace | Unified facade combining all three |

Your host application depends on plugwerk-spi at compile time (which defines these interfaces) and loads the client plugin ZIP at runtime. This separation keeps your application's classpath clean — the client plugin brings its own HTTP client and serialization libraries in an isolated classloader.

Distribution

Section titled “Distribution”

The client plugin is published on Maven Central as a ZIP artifact:

  • Group: io.plugwerk
  • Artifact: plugwerk-client-plugin
  • Classifier: pf4j
  • Type: zip

You can pull it as a Gradle/Maven dependency or download it manually from Maven Central. See Installation for detailed setup instructions.

Multi-Server and Multi-Namespace Support

Section titled “Multi-Server and Multi-Namespace Support”

Your host application can manage connections to multiple Plugwerk Servers and multiple namespaces within the same server. Each PlugwerkPlugin.connect(config) call returns an independent, AutoCloseable PlugwerkMarketplace — composition and lifecycle (typically a small holder class or a set of Spring beans) are the host's responsibility.

This is useful when your application needs to pull plugins from different sources — for example, a production server and a staging server, or separate namespaces for different plugin categories.

See Configuration for examples of the Builder API and multi-server setup, or jump to the Examples chapter for two fully runnable host applications (a Java CLI and a Spring Boot + Thymeleaf web app) that wire the client plugin into a real workflow.

Classloader Isolation

Section titled “Classloader Isolation”

The client plugin runs inside PF4J's isolated classloader. This means:

  • No dependency conflicts — the plugin bundles OkHttp and Jackson without affecting your application's classpath
  • Clean separation — your application only depends on the lightweight plugwerk-spi interfaces
  • Safe upgrades — updating the client plugin does not require recompiling your application

Key Characteristics

Section titled “Key Characteristics”

| Aspect | Detail | | ------------------- | --------------------------------------------------------- | | Packaging | PF4J ZIP bundle (JAR + dependencies in lib/) | | Runtime requirement | PF4J plugin manager in the host application | | Compile dependency | plugwerk-spi only (lightweight, no transitive deps) | | Authentication | API key or JWT bearer token per configuration | | Transport | HTTPS via OkHttp with configurable timeouts | | Artifact integrity | SHA-256 checksum verification on every plugin download |