Add 'ServiceLoader interoperability' section in readme

1 files changed, 33 insertions, 0 deletions

diff --git a/README.md b/README.md
index 4a8e48a..5cc8b67 100644
--- a/README.md
+++ b/README.md
@@ -343,6 +343,39 @@ 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()` 
+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`. 
+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. 
+In this case the format of `META-INF/services/ro.fortsoft.pf4j.demo.api.Greeting` is
+```
+# Generated by PF4J
+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 
+an extension of `Greeting` by PF4J (at runtime).
+
+You can plug your custom `ExtensionStorage` implementation in `ExtensionAnnotationProcessor` in two possible modes:
+- set the annotation procesor option with key `pf4j.storageClassName`
+- set the system property with key `pf4j.storageClassName`
+
+For example if I want to use `ServiceProviderExtensionStorage` then the value for the `pf4j.storageClassName` key must be
+`ro.fortsoft.pf4j.processor.ServiceProviderExtensionStorage`
+
 Demo
 -------------------
 I have a tiny demo application. The demo application is in demo folder.