You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Decebal Suiu f66859f71c Resolve #335 2 weeks ago
demo [maven-release-plugin] prepare for next development iteration 2 months ago
demo_gradle Tabs to spaces 1 year ago
maven-archetypes/quickstart [maven-release-plugin] prepare for next development iteration 2 months ago
pf4j Resolve #335 2 weeks ago
.editorconfig fix typo 3 years ago
.gitignore Fix bug in loadJars() (#131) 2 years ago
.travis.yml Development is done on Java 11 (OpenJDK) 5 months ago
CHANGELOG.md Update changelog 2 months ago
LICENSE Added LICENSE file 1 year ago
README.md Update README.md 2 months ago
pf4j-logo.png Create a PF4J logo (#162) 1 year ago
pf4j-logo.svg Create a PF4J logo (#162) 1 year ago
pom.xml [maven-release-plugin] prepare for next development iteration 2 months ago
run-demo.bat Improve run-demo scripts 6 months ago
run-demo.sh Improve run-demo scripts 6 months ago

README.md

Plugin Framework for Java (PF4J)

Travis CI Build Status Coverage Status Maven Central

A plugin is a way for a third party to extend the functionality of an application. A plugin implements extension points declared by application or other plugins. Also a plugin can define extension points.

NOTE: Starting with version 0.9 you can define an extension directly in the application jar (you’re not obligated to put the extension in a plugin - you can see this extension as a default/system extension). See WhazzupGreeting for a real example.

Features/Benefits

With PF4J you can easily transform a monolithic java application in a modular application.
PF4J is an open source (Apache license) lightweight (around 50 KB) plugin framework for java, with minimal dependencies (only slf4j-api) and very extensible (see PluginDescriptorFinder and ExtensionFinder).

Practically PF4J is a microframework and the aim is to keep the core simple but extensible. I try to create a little ecosystem (extensions) based on this core with the help of the comunity.
For now are available these extensions:

No XML, only Java.

You can mark any interface or abstract class as an extension point (with marker interface ExtensionPoint) and you specified that an class is an extension with @Extension annotation.

Also, PF4J can be used in web applications. For my web applications when I want modularity I use pf4j-wicket.

Components

  • Plugin is the base class for all plugins types. Each plugin is loaded into a separate class loader to avoid conflicts.
  • PluginManager is used for all aspects of plugins management (loading, starting, stopping). You can use a built-in implementation as JarPluginManager, ZipPluginManager, DefaultPluginManager (it’s a JarPluginManager + ZipPluginManager) or you can implement a custom plugin manager starting from AbstractPluginManager (implement only factory methods).
  • PluginLoader loads all information (classes) needed by a plugin.
  • ExtensionPoint is a point in the application where custom code can be invoked. It’s a java interface marker.
    Any java interface or abstract class can be marked as an extension point (implements ExtensionPoint interface).
  • Extension is an implementation of an extension point. It’s a java annotation on a class.

PLUGIN = a container for EXTENSION POINTS and EXTENSIONS + lifecycle methods (start, stop, delete)

A PLUGIN is similar with a MODULE from other systems. If you don’t need lifecycle methods (hook methods for start, stop, delete) you are not forced to supply a plugin class (the PluginClass property from the plugin descriptor is optional). You only need to supply some description of plugin (id, version, author, …) for a good tracking (your application wants to know who supplied the extensions or extensions points).

How to use

It’s very simple to add pf4j in your application.

Define an extension point in your application/plugin using ExtensionPoint interface marker:

public interface Greeting extends ExtensionPoint {

    String getGreeting();

}

Create an extension using @Extension annotation:

@Extension
public class WelcomeGreeting implements Greeting {

    public String getGreeting() {
        return "Welcome";
    }

}

Create (it’s optional) a Plugin class if you are interested for plugin’s lifecycle events (start, stop, …):

public class WelcomePlugin extends Plugin {

    public WelcomePlugin(PluginWrapper wrapper) {
        super(wrapper);

        // you can use "wrapper" to have access to the plugin context (plugin manager, descriptor, ...)
    }

    @Override
    public void start() {
        System.out.println("WelcomePlugin.start()");
    }

    @Override
    public void stop() {
        System.out.println("WelcomePlugin.stop()");
    }
    
    @Override
    public void delete() {
        System.out.println("WelcomePlugin.delete()");
    }
    
}

In above code I created a plugin (welcome) that comes with one extension for the Greeting extension point.

You can distribute you plugin as a jar file (the simple solution). In this case add the plugin’s metadata in MANIFEST.MF file of jar:

Manifest-Version: 1.0
Archiver-Version: Plexus Archiver
Created-By: Apache Maven
Built-By: decebal
Build-Jdk: 1.6.0_17
Plugin-Class: org.pf4j.demo.welcome.WelcomePlugin
Plugin-Dependencies: x, y, z
Plugin-Id: welcome-plugin
Plugin-Provider: Decebal Suiu
Plugin-Version: 0.0.1

In above manifest I described a plugin with id welcome-plugin (mandatory attribute), with class org.pf4j.demo.welcome.WelcomePlugin (optional attribute), with version 0.0.1 (mandatory attribute) and with dependencies to plugins x, y, z (optional attribute).

Now you can play with plugins and extensions in your code:

public static void main(String[] args) {
    ...

    // create the plugin manager
    PluginManager pluginManager = new JarPluginManager(); // or "new ZipPluginManager() / new DefaultPluginManager()"
    
    // start and load all plugins of application
    pluginManager.loadPlugins();
    pluginManager.startPlugins();

    // retrieve all extensions for "Greeting" extension point
    List<Greeting> greetings = pluginManager.getExtensions(Greeting.class);
    for (Greeting greeting : greetings) {
        System.out.println(">>> " + greeting.getGreeting());
    }
    
    // stop and unload all plugins
    pluginManager.stopPlugins();
    pluginManager.unloadPlugins();
    
    ...
}

The output is:

>>> Welcome

PF4J is very customizable and comes with a lot of goodies. Please read the documentation to discover yourself the power of this library.

Documentation

Documentation is available on pf4j.org

Demo

Demo applications are available in demo folder