PluginManager pluginManager = new DefaultPluginManager();
pluginManager.loadPlugins();
pluginManager.startPlugins();
...
}
```
In above code, I created a **DefaultPluginManager** (it's the default implementation for
**PluginManager** interface) that loads and starts all active(resolved) plugins.
Each available plugin is loaded using a different java class loader, **PluginClassLoader**.
The **PluginClassLoader** contains only classes found in **PluginClasspath** (default _classes_ and _lib_ folders) of plugin and runtime classes and libraries of the required/dependent plugins. This class loader is a _Parent Last ClassLoader_ - it loads the classes from the plugin's jars before delegating to the parent class loader.
The plugins are stored in a folder. You can specify the plugins folder in the constructor of DefaultPluginManager. If the plugins folder is not specified
then the location is returned by `System.getProperty("pf4j.pluginsDir", "plugins")`.
The structure of plugins folder is:
* plugin1.zip (or plugin1 folder)
* plugin2.zip (or plugin2 folder)
It's very simple to add pf4j in your application.
In plugins folder you can put a plugin as folder or archive file (zip).
A plugin folder has this structure by default:
* `classes` folder
* `lib` folder (optional - if the plugin used third party libraries)
The plugin manager searches plugins metadata using a **PluginDescriptorFinder**.
**DefaultPluginDescriptorFinder** is a "link" to **ManifestPluginDescriptorFinder** that lookups plugins descriptors in MANIFEST.MF file.
In this case the `classes/META-INF/MANIFEST.MF` file looks like:
```
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`, with class `org.pf4j.demo.welcome.WelcomePlugin`, with version `0.0.1` and with dependencies
to plugins `x, y, z`.
**NOTE:** The plugin version must be compliant with [Semantic Versioning](http://semver.org) (PF4J uses `jsemver` as implementation for SemVer because it comes with support for comparing versions)
You can define an extension point in your application using **ExtensionPoint** interface marker.
Define an extension point in your application using **ExtensionPoint** interface marker:
```java
public interface Greeting extends ExtensionPoint {
@ -141,10 +53,8 @@ public interface Greeting extends ExtensionPoint {
}
```
Another important internal component is **ExtensionFinder** that describes how the plugin manager discovers extensions for the extensions points.
**DefaultExtensionFinder** looks up extensions using **Extension** annotation.
DefaultExtensionFinder looks up extensions in all extensions index files `META-INF/extensions.idx`. PF4J uses Java Annotation Processing to process at compile time all classes annotated with @Extension and to produce the extensions index file.
Create a plugin that contribute with an extension:
```java
public class WelcomePlugin extends Plugin {
@ -164,403 +74,65 @@ public class WelcomePlugin extends Plugin {
}
```
In above code I supply an extension for the `Greeting` extension point.
In above code I created a plugin that comes with one extension for the `Greeting` extension point.
You can retrieve all extensions for an extension point with:
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:
You can inject your custom component (for example PluginDescriptorFinder, ExtensionFinder, PluginClasspath, ...) in DefaultPluginManager just override `create...` methods (factory method pattern).
PF4J can be used in Kotlin project as well. One has to use the Kotlin annotation processing tool
[**kapt**](https://kotlinlang.org/docs/reference/kapt.html) for the plugin project written in Kotlin.
The demo_gradle project contains one plugin project _plugin3_ written in Kotlin for demonstration.
Plugin assembly
------------------------------
After you developed a plugin the next step is to deploy it in your application. For this task, one option is to create a zip file with a structure described in section [How to use](https://github.com/decebals/pf4j/blob/master/README.md#how-to-use) from the beginning of the document.
If you use `apache maven` as build manger then your pom.xml file must looks like [this](https://github.com/decebals/pf4j/blob/master/demo/plugins/plugin1/pom.xml). This file it's very simple and it's self explanatory.
If you use `apache ant` then your build.xml file must looks like [this](https://github.com/gitblit/gitblit-powertools-plugin/blob/master/build.xml). In this case please look at the "build" target.
Plugin lifecycle
--------------------------
Each plugin passes through a pre-defined set of states. [PluginState](https://github.com/decebals/pf4j/blob/master/pf4j/src/main/java/org/pf4j/PluginState.java) defines all possible states.
The primary plugin states are:
* CREATED
* DISABLED
* STARTED
* STOPPED
The DefaultPluginManager contains the following logic:
* all plugins are resolved & loaded
* *DISABLED* plugins are NOT automatically *STARTED* by pf4j in `startPlugins()` BUT you may manually start (and therefore enable) a *DISABLED* plugin by calling `startPlugin(pluginId)` instead of `enablePlugin(pluginId)` + `startPlugin(pluginId)`
* only *STARTED* plugins may contribute extensions. Any other state should not be considered ready to contribute an extension to the running system.
The differences between a DISABLED plugin and a STARTED plugin are:
* a STARTED plugin has executed Plugin.start(), a DISABLED plugin has not
* a STARTED plugin may contribute extension instances, a DISABLED plugin may not
DISABLED plugins still have valid class loaders and their classes can be manually
loaded and explored, but the resource loading - which is important for inspection -
has been handicapped by the DISABLED check.
As integrators of pf4j evolve their extension APIs it will become
a requirement to specify a minimum system version for loading plugins.
Loading & starting a newer plugin on an older system could result in
runtime failures due to method signature changes or other class
differences.
For this reason was added a manifest attribute (in PluginDescriptor) to specify a 'requires' version
which is a minimum system version on x.y.z format, or a
specify the system version of the plugin manager and the logic to disable
plugins on load if the system version is too old (if you want total control,
please override `isPluginValid()`). This works for both `loadPlugins()` and `loadPlugin()`.
__PluginStateListener__ defines the interface for an object that listens to plugin state changes. You can use `addPluginStateListener()` and `removePluginStateListener()` from PluginManager if you want to add or remove a plugin state listener.
Your application, as a PF4J consumer, has full control over each plugin (state). So, you can load, unload, enable, disable, start, stop and delete a certain plugin using PluginManager (programmatically).
Custom PluginManager
--------------------------
To create a custom plugin manager you could:
* implements `PluginManager` interface (create a plugin manager from scratch)
* modifies some aspects/behaviors of built-in implementations (`DefaultPluginManager`, `JarPluginManager`)
* extends `AbstractPluginManager` class
`JarPluginManager` is a `PluginManager` that loads plugin from a jar file. Actually, a plugin is a fat jar, a jar which contains classes from all the libraries,
on which your project depends and, of course, the classes of current project.
`AbstractPluginManager` adds some glue that help you to create quickly a plugin manager. All you need to do is to implement some factory methods.
PF4J uses in many places the factory method pattern to implement the dependency injection (DI) concept in a manually mode.
See below the abstract methods for `AbstractPluginManager`:
```java
public abstract class AbstractPluginManager implements PluginManager {
In above manifest I described a plugin with id `welcome-plugin`, with class `org.pf4j.demo.welcome.WelcomePlugin`, with version `0.0.1` and with dependencies
to plugins `x, y, z`.
`DefaultPluginManager` contributes with "default" components (`DefaultExtensionFactory`, `DefaultPluginFactory`, `DefaultPluginLoader`, ...) to `AbstractPluginManager`.
Most of the times it's enough to extends `DefaultPluginManager` and to supply your custom components.
Starting with version 2.0 it's possible to coexist multiple plugins types (jar, zip, directory) in the same `PluginManager`.
For example, `DefaultPluginManager` works out of the box with zip and jar plugins. The idea is that `DefaultPluginManager` uses a compound version for:
So, it's very easy to add new strategies for plugin descriptor finder, plugin loader and plugin repository.
Development mode
--------------------------
PF4J can run in two modes: **DEVELOPMENT** and **DEPLOYMENT**.
The DEPLOYMENT(default) mode is the standard workflow for plugins creation: create a new Maven module for each plugin, codding the plugin (declares new extension points and/or
add new extensions), pack the plugin in a zip file, deploy the zip file to plugins folder. These operations are time consuming and from this reason I introduced the DEVELOPMENT runtime mode.
The main advantage of DEVELOPMENT runtime mode for a plugin developer is that he/she is not enforced to pack and deploy the plugins. In DEVELOPMENT mode you can developing plugins in a simple and fast mode.
Lets describe how DEVELOPMENT runtime mode works.
First, you can change the runtime mode using the "pf4j.mode" system property or overriding `DefaultPluginManager.getRuntimeMode()`.
For example I run the pf4j demo in eclipse in DEVELOPMENT mode adding only `"-Dpf4j.mode=development"` to the pf4j demo launcher.
You can retrieve the current runtime mode using `PluginManager.getRuntimeMode()` or in your Plugin implementation with `getWrapper().getRuntimeMode()`(see [WelcomePlugin](https://github.com/decebals/pf4j/blob/master/demo/plugins/plugin1/src/main/java/org/pf4j/demo/welcome/WelcomePlugin.java)).
The DefaultPluginManager determines automatically the correct runtime mode and for DEVELOPMENT mode overrides some components(pluginsDirectory is __"../plugins"__, __PropertiesPluginDescriptorFinder__ as PluginDescriptorFinder, __DevelopmentPluginClasspath__ as PluginClassPath).
Another advantage of DEVELOPMENT runtime mode is that you can execute some code lines only in this mode (for example more debug messages).
**NOTE:** If you use Eclipse then make sure annotation processing is enabled at least for any projects registering objects using annotations. In the properties for your new project go to __Java Compiler > Annotation Processing__
Check the __“Enable Project Specific Settings”__ and make sure __“Enable annotation processing”__ is checked.
If you use Maven as build manger, after each dependency modification in your plugin (Maven module) you must run __Maven > Update Project...__
For more details see the demo application.
Enable/Disable plugins
-------------------
In theory, it's a relation **1:N** between an extension point and the extensions for this extension point.
This works well, except for when you develop multiple plugins for this extension point as different options for your clients to decide on which one to use.
In this situation you wish a possibility to disable all but one extension.
For example I have an extension point for sending mail (EmailSender interface) with two extensions: one based on Sendgrid and another
based on Amazon Simple Email Service.
The first extension is located in Plugin1 and the second extension is located in Plugin2.
I want to go only with one extension ( **1:1** relation between extension point and extensions) and to achieve this I have two options:
1) uninstall Plugin1 or Plugin2 (remove folder pluginX.zip and pluginX from plugins folder)
2) disable Plugin1 or Plugin2
For option two you must create a simple file **enabled.txt** or **disabled.txt** in your plugins folder.
The content for **enabled.txt** is similar with:
```
########################################
# - load only these plugins
# - add one plugin id on each line
# - put this file in plugins folder
########################################
welcome-plugin
```
The content for **disabled.txt** is similar with:
```
########################################
# - load all plugins except these
# - add one plugin id on each line
# - put this file in plugins folder
########################################
welcome-plugin
```
All comment lines (line that start with # character) are ignored.
If a file with enabled.txt exists then disabled.txt is ignored. See enabled.txt and disabled.txt from the demo folder.
Default/System extension
-------------------
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](https://github.com/decebals/pf4j/blob/master/demo/app/src/main/java/org/pf4j/demo/WhazzupGreeting.java)
for a real example.
This is great for starting application phase. In this scenario you have a minimalist plugin framework with one class loader
(the application class loader), similar with Java [ServiceLoader](https://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html)
but with the following benefits:
- no need to write provider-configuration files in the resource directory `META-INF/services`, you using the elegant
`@Extension` annotation from PF4J
- anytime you can switch to the multiple class loader mechanism without to change one code line in your application
Of course the code present in the `Boot` class from the demo application it is functional but you can use a more minimalist code
skipping `pluginManager.loadPlugins()` and `pluginManager.startPlugins()`.
```java
public static void main(String[] args) {
// create the plugin manager
PluginManager pluginManager = new DefaultPluginManager();
Below are listed some problems that may occur when attempting to use PF4J, and suggestions for solving them.
- **No Extensions Found**
See if you have a file `extensions.idx` in each plugin.
If file `extensions.idx` doesn't exist then probably there is something wrong with the annotation processing step (enable annotation processing in your IDE or in your Maven script).
If file `extensions.idx` exists and it's not empty then sure you have a class loader issue (you have the same extension point in two different class loader), in this situation you must remove some libraries (probably the API jar) from plugin.
PF4J is very customizable and comes with a lot of goodies. Please read the documentation to discover yourself the power of this library.
If the problem persist or you want to find more info related to the extensions discovery process (e.g what interfaces/classes are loaded by each plugin, what classes are not recognized as extensions for an extension point) then you must put on `TRACE` level the logger for `PluginClassLoader` and `AbstractExtensionFinder` (see the [log4j.properties](https://github.com/decebals/pf4j/blob/master/demo/app/src/main/resources/log4j.properties) file for demo).
Are some resources on the internet related to this subject: [#82](https://github.com/decebals/pf4j/issues/82), [#64](https://github.com/decebals/pf4j/issues/64) and [No extensions found] (https://groups.google.com/forum/#!topic/pf4j/tEQXY_WpD3A).
Documentation
---------------
Documentation is available on [pf4j.ro](http://www.pf4j.org)
Demo
-------------------
I have a tiny demo application. The demo application is in demo folder.
In demo/api folder I declared an extension point ( _Greeting_).
In demo/plugins I implemented two plugins: plugin1, plugin2 (each plugin adds an extension for _Greeting_).
To run the demo application use:
```
./run-demo.sh (for Linux/Unix)
./run-demo.bat (for Windows)
```
How to build
-------------------
Requirements:
- [Git](http://git-scm.com/)
- JDK 7 (test with `java -version`)
- [Apache Maven 3](http://maven.apache.org/) (test with `mvn -version`)
Steps:
- create a local clone of this repository (with `git clone https://github.com/decebals/pf4j.git`)
- go to project's folder (with `cd pf4j`)
- build the artifacts (with `mvn clean package` or `mvn clean install`)
After above steps a folder _pf4j/target_ is created and all goodies are in that folder.
Mailing list
--------------
Much of the conversation between developers and users is managed through [mailing list] (http://groups.google.com/group/pf4j).
Versioning
------------
PF4J will be maintained under the Semantic Versioning guidelines as much as possible.
Releases will be numbered with the follow format:
`<major>.<minor>.<patch>`
And constructed with the following guidelines:
* Breaking backward compatibility bumps the major
* New additions without breaking backward compatibility bumps the minor
* Bug fixes and misc changes bump the patch
For more information on SemVer, please visit http://semver.org/.
License
--------------
Copyright 2012 Decebal Suiu
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with
the License. You may obtain a copy of the License in the LICENSE file, or at:
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.
---------------
Demo applications are available in [demo](https://github.com/decebals/pf4j/tree/master/demo) folder
Decebal Suiu
7 years ago