first commit

1 files changed, 151 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..aa038a2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,151 @@
+Plugin Framework for Java (PF4J)
+=====================
+
+A plugin is a way for a third party to extend the functionality of an application. A plugin implements extensions points
+declared by application or another plugins. Also a plugin can defines extension points.
+
+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).
+- **ExtensionPoint** is a point in the application where custom code can be invoked.
+- **Extension** is an implementation of extension point.
+
+Artifacts
+-------------------
+- PF4J `pf4j` (jar)
+- PF4J Demo `pf4j-demo` (executable jar)
+
+Using Maven
+-------------------
+
+First you must install the pf4j artifacts in your local maven repository with:
+
+    mvn clean install
+
+I will upload these artifacts in maven central repository as soon as possible.
+
+In your pom.xml you must define the dependencies to PF4J artifacts with:
+
+```xml
+<dependency>
+    <groupId>org.pf4j</groupId>
+    <artifactId>pf4j</artifactId>
+    <version>${pf4j.version}</version>
+</dependency>    
+```
+
+where ${pf4j.version} is the last pf4j version.
+
+How to use
+-------------------
+It's very simple to add pf4j in your application:
+
+    public static void main(String[] args) {
+    	...
+    	
+        PluginManager pluginManager = new DefaultPluginManager();
+        pluginManager.loadPlugins();
+        pluginManager.startPlugins();
+
+        ...
+    }
+
+In above code, I created a DefaultPluginManager (it's the default implementation for
+PluginManager interface) that load and start all active(resolved) plugins.
+The plugins are stored in a folder. You can specify the plugins folder in constructor of DefaultPluginManager
+or using the constructor without parameters (in this case plugins folder is returned by System.getProperty("pf4j.pluginsDir", "plugins")).
+
+The structure of plugins folder is:
+- plugin1.zip (or plugin1 folder)
+- plugin2.zip (or plugin2 folder)
+...
+- pluginN.zip (or pluginN folder)
+
+In plugins folder you can put a plugin as folder or archive file (zip).
+A plugin folder has this structure:
+- `classes` folder
+- `lib` folder (optional - if the plugin used third party libraries)
+
+The plugin manager discovers plugins metadata using a PluginDescriptorFinder. DefaultPluginDescriptorFinder lookup plugin descriptor in MANIFEST.MF file.
+In this case the classes/META-INF/MANIFEST.MF 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`.
+
+You can define an extension point in your application using ExtensionPoint interface marker.
+
+    public interface Greeting extends ExtensionPoint {
+
+        public String getGreeting();
+
+    }
+
+Another important internal component is ExtensionFinder that describes how plugin manager discovers extensions for extensions points. DefaultExtensionFinder look up extensions using Extension annotation.
+
+    public class WelcomePlugin extends Plugin {
+
+        public WelcomePlugin(PluginWrapper wrapper) {
+            super(wrapper);
+        }
+
+        @Extension
+        public static class WelcomeGreeting implements Greeting {
+
+            public String getGreeting() {
+                return "Welcome";
+            }
+
+        }
+
+    }
+
+In above code I supply an extension for the Greeting extension point.
+
+You can retrieves all extensions for an extension point with:
+
+    List<ExtensionWrapper<Greeting>> greetings = pluginManager.getExtensions(Greeting.class);
+    for (ExtensionWrapper<Greeting> greeting : greetings) {
+    	System.out.println(">>> " + greeting.getInstance().getGreeting());
+    }
+
+
+For more information please see the demo sources.
+
+Demo
+-------------------
+
+I have a tiny demo application. In this demo I have implemented two widgets types:
+a chart widget (using open flash chart) and a text widget (display a Lorem Ipsum).
+You can drag and drop widgets, perform some actions on each widget, add or remove new
+widgets, change widget settings, collapse widgets.
+
+The demo application is in demo folder.
+To run the demo application use:  
+ 
+    ./run-demo.sh
+
+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.