diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 77 |
1 files changed, 39 insertions, 38 deletions
@@ -31,9 +31,10 @@ Also, PF4J can be used in web applications. For my web applications when I want 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). +- **PluginManager** is used for all aspects of plugins management (loading, starting, stopping). You can use a built-in implementation as `DefaultPluginManager`, `JarPluginManager` 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). +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. Artifacts @@ -81,7 +82,7 @@ It's very simple to add pf4j in your application: ```java public static void main(String[] args) { ... - + PluginManager pluginManager = new DefaultPluginManager(); pluginManager.loadPlugins(); pluginManager.startPlugins(); @@ -94,7 +95,7 @@ In above code, I created a **DefaultPluginManager** (it's the default implementa **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 +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 than the location is returned by `System.getProperty("pf4j.pluginsDir", "plugins")`. The structure of plugins folder is: @@ -123,7 +124,7 @@ Plugin-Provider: Decebal Suiu Plugin-Version: 0.0.1 ``` -In above manifest I described a plugin with id `welcome-plugin`, with class `ro.fortsoft.pf4j.demo.welcome.WelcomePlugin`, with version `0.0.1` and with dependencies +In above manifest I described a plugin with id `welcome-plugin`, with class `ro.fortsoft.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) @@ -188,7 +189,7 @@ protected PluginDescriptorFinder createPluginDescriptorFinder() { return new PropertiesPluginDescriptorFinder(); } ``` - + and in plugin repository you must have a plugin.properties file with the below content: ``` @@ -198,13 +199,13 @@ plugin.id=welcome-plugin plugin.provider=Decebal Suiu plugin.version=0.0.1 ``` - -You can control extension instance creation overriding `createExtensionFactory` method from DefaultExtensionFinder. -Also, you can control plugin instance creation overriding `createPluginFactory` method from DefaultExtensionFinder. + +You can control extension instance creation overriding `createExtensionFactory` method from DefaultExtensionFinder. +Also, you can control plugin instance creation overriding `createPluginFactory` method from DefaultExtensionFinder. For more information please see the demo sources. -**NOTE:** If your application didn't find extensions then make sure that you have a file with name `extensions.idx` +**NOTE:** If your application didn't find extensions then make sure that you have a file with name `extensions.idx` generated by PF4J in the plugin jar. It's most likely that they are some problems with the annotation processing mechanism from Java. O possible solution to resolve your problem is to add a configuration to your maven build. @@ -219,7 +220,7 @@ The `maven-compiler-plugin` can be configured to do this like so: <annotationProcessor>ro.fortsoft.pf4j.processor.ExtensionAnnotationProcessor</annotationProcessor> </annotationProcessors> </configuration> -</plugin> +</plugin> ``` Plugin assembly @@ -247,7 +248,7 @@ The differences between a DISABLED plugin and a STARTED plugin are: * 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 - +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 @@ -267,7 +268,7 @@ Your application, as a PF4J consumer, has full control over each plugin (state). 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 +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. @@ -277,13 +278,13 @@ First, you can change the runtime mode using the "pf4j.mode" system property or 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/ro/fortsoft/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). +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 than 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. +For more details see the demo application. Enable/Disable plugins ------------------- @@ -321,24 +322,24 @@ welcome-plugin ``` All comment lines (line that start with # character) are ignored. -If a file with enabled.txt exists than disabled.txt is ignored. See enabled.txt and disabled.txt from the demo folder. +If a file with enabled.txt exists than 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/ro/fortsoft/pf4j/demo/WhazzupGreeting.java) +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/ro/fortsoft/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) +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()`. +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) { @@ -367,19 +368,19 @@ public static void main(String[] args) { ServiceLoader interoperability ------------------- Starting with version 0.12 PF4J comes with a better support for `ServiceLoader`. -PF4J can read `META-INF/services` (Java Service Provider mechanism) as extensions, so, -if you have a modular application based on `java.util.ServiceLoader` class you can replace entirely the `ServiceLoader.load()` +PF4J can read `META-INF/services` (Java Service Provider mechanism) as extensions, so, +if you have a modular application based on `java.util.ServiceLoader` class you can replace entirely the `ServiceLoader.load()` calls from your application with `PluginManager.getExtensions()` and migrate smooth from ServiceLoader to PF4J. -Also you have the possibility to change the `ExtensionStorage` used in `ExtensionAnnotationProcessor`. +Also you have the possibility to change the `ExtensionStorage` used in `ExtensionAnnotationProcessor`. By default we use the format with `META-INF/extensions.idx` ``` ro.fortsoft.pf4j.demo.HowdyGreeting ro.fortsoft.pf4j.demo.WhazzupGreeting ``` - -but you can use a more standard location and format, `META-INF/services/<extension-point>`, used by Java Service Provider -(see `java.util.ServiceLoader`) via `ServiceProviderExtensionStorage` implementation. + +but you can use a more standard location and format, `META-INF/services/<extension-point>`, used by Java Service Provider +(see `java.util.ServiceLoader`) via `ServiceProviderExtensionStorage` implementation. In this case the format of `META-INF/services/ro.fortsoft.pf4j.demo.api.Greeting` is ``` # Generated by PF4J @@ -387,7 +388,7 @@ ro.fortsoft.pf4j.demo.HowdyGreeting ro.fortsoft.pf4j.demo.WhazzupGreeting # pf4j extension ``` -where the `ro.fortsoft.pf4j.demo.HowdyGreeting` entry is legacy (it's not generated by PF4J) but it's seen as +where the `ro.fortsoft.pf4j.demo.HowdyGreeting` entry is legacy (it's not generated by PF4J) but it's seen as an extension of `Greeting` by PF4J (at runtime). You can plug your custom `ExtensionStorage` implementation in `ExtensionAnnotationProcessor` in two possible modes: @@ -403,7 +404,7 @@ not added/enabled by default. To do this please override `createExtensionFinder` protected ExtensionFinder createExtensionFinder() { DefaultExtensionFinder extensionFinder = super.createExtensionFinder(); extensionFinder.addServiceProviderExtensionFinder(); - + return extensionFinder; } ``` @@ -429,7 +430,7 @@ 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) @@ -437,14 +438,14 @@ To run the demo application use: How to build ------------------- -Requirements: -- [Git](http://git-scm.com/) +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`) +- 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. @@ -472,12 +473,12 @@ 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. |