Skip to content
Sign up
This repository

public / spring-plugin Octocat-spinner-32

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Updated README. 

Added section on @EnablePluginRegistries. General polishing.
  • Loading branch information...
commit 3f941603a79aafa32d83712aa5222fd57f4a1612 1 parent 50857dc
Oliver Gierke authored

Showing 1 changed file with 23 additions and 22 deletions. Show Diff Stats Hide Diff Stats

  1. 45  README.markdown
45  README.markdown
Source Rendered
View 
@@ -2,21 +2,13 @@
2 2
3 3 
 V0.8 - Oliver Gierke, SpringSource - a division of VMware
4 4
5   
-© 2008-2012 The original authors
6   
-
7   
-## Revision History
8   
-
9   
-* 04.11.2008 Oliver Gierke Initial draft
10   
-* 05.11.2008 Oliver Gierke Added metadata module documentation
11   
-* 24.01.2009 Oliver Gierke Added remark to inner bean usage
12   
-* 23.03.2009 Oliver Gierke Added section on plugin ordering
13   
-* 21.02.2012 Oliver Gierke Move project to SpringSource
  5 
+© 2008-2012 The original authors
14 6
15 7 
 ## Preface
16 8
17 9 
 ### Introduction
18 10
19   
-Building extensible architectures nowadays is a core principle to create maintainable applications. This is why fully fledged plugin environments like *OSGi* are so poular these days. Unfortunately the introduction of *OSGi* introduces a lot of complexity to projects.
  11 
+Building extensible architectures nowadays is a core principle to create maintainable applications. This is why fully fledged plugin environments like *OSGi* are so popular these days. Unfortunately the introduction of *OSGi* introduces a lot of complexity to projects.
20 12
21 13 
 Spring Plugin provides a more pragmatic approach to plugin development by providing the core flexibility of having plugin implementations extending a core system's functionality but of course not delivering core OSGi features like dynamic class loading or runtime installation and deployment of plugins. Although Spring Plugin thus is not nearly as powerful as OSGi, it servers poor man's requirements to build a modular
22 14 
 extensible application.
 
@@ -36,7 +28,7 @@ lot of momentum in collaborative use with Spring.
36 28
37 29 
 #### Spring
38 30
39   
-Spring is the defacto standard application framework for Java applications. Its consistent programming model, easy configuration and wide support for all kinds of third party libraries makes it the first class citizen of application frameworks. Spring Plugin tightly integrates into Spring's component model and extends the core container
  31 
+Spring is the de-facto standard application framework for Java applications. Its consistent programming model, easy configuration and wide support for all kinds of third party libraries makes it the first class citizen of application frameworks. Spring Plugin tightly integrates into Spring's component model and extends the core container
40 32 
 with some custom functionality.
41 33
42 34 
 ## Core
 
@@ -126,17 +118,17 @@ support**
126 118
127 119 
 ~~~~xml
128 120 
 <!-- In a file called plugins.xml in the plugin project -->
129   
-<bean class="MyPluginimplementation" />
  121 
+<bean class="MyPluginImplementation" />
130 122 
 ~~~~
131 123
132   
-You can see that we include a wildcarded configurationfile that allows plugin projects to easily contribute plugin implementations by declaring them as beans in configuration files matching the wildcarded path. If you use Spring 2.5 component scanning you don't have to use the import trick at all as Spring would detect the implementation automatically as long as it is annotated with `@Component`, `@Service` a.s.o.
  124 
+You can see that we include a wildcarded configuration file that allows plugin projects to easily contribute plugin implementations by declaring them as beans in configuration files matching the wildcarded path. If you use Spring 2.5 component scanning you don't have to use the import trick at all as Spring would detect the implementation automatically as long as it is annotated with `@Component`, `@Service` a.s.o.
133 125
134 126 
 The `BeanListBeanFactory` in turn allows registering a map of lists to be created, where the maps entry key is the id under which the list will be registered and the entry's value is the type to be looked up.
135 127
136 128 
 > #### Note
137 129 
 >
138 130 
 > The design of the `BeanListBeanFactory` might seem a little confusing at first
139   
-> (especially to set a map on a property named lists). This is due to the posibility to
  131 
+> (especially to set a map on a property named lists). This is due to the possibility to
140 132 
 > register more than one list to be looked up. We think about dropping this
141 133 
 > functionality for the sake of simplicity in future versions.
142 134 
 
@@ -224,7 +216,7 @@ registry.getPluginFor(ProductType.SOFTWARE, new DefaultPlugin());
224 216 
 registry.getPluginsFor(ProductType.HARDWARE, new MyException("Damn!");
225 217 
 ~~~~
226 218
227   
-#### Configuration and namespace
  219 
+#### Configuration, XML namespace and @EnablePluginRegistries
228 220
229 221 
 Similar to the `BeanListBeanFactory` described in [Collecting Spring beans
230 222 
 dynamically](#core.beans-dynamically) Spring Plugin provides a `PluginRegistryBeanFactory` to automatically lookup beans of a dedicated type to be aggregated in a `PluginRegistry`. Note that the type has to be assignable to `Plugin` to let the registry work as expected.
 
@@ -233,19 +225,28 @@ Furthermore there is also an element in the namespace to shrink down configurati
233 225
234 226 
 **Example 1.8. Using the XML namespace to configure a registry**
235 227
236   
-~~~~xml
  228 
+```xml
237 229 
 <plugin:registry id="plugins" class="com.acme.MyPluginInterface" />
238   
-~~~~
  230 
+```
  231 
+
  232 
+As of version 0.8 creating a `PluginRegistry` can also be achieved using the `@EnablePluginRegistries` annotation:
  233 
+
  234 
+```java
  235 
+@Configuration
  236 
+@EnablePluginRegistries(MyPluginInterface.class)
  237 
+class ApplicationConfiguration { … }
  238 
+```
  239 
+
  240 
+This configuration snippet will register a `OrderAwarePluginRegistry` for `MyPluginInterface` within the `ApplicationContext` and thus make it available for injection into client beans. The registered bean will be named `myPluginInterfaceRegistry` so that it can be explicitly referenced on the client side using the `@Qualifier` annotation if necessary. The bean name can be customized using `@Qualifier` on the plugin interface definition.
239 241
240 242 
 ### Ordering plugins
241 243
242   
-Declaring plugin beans sometimes it is necessary to preserve a certain order of plugins. Suppose you have a plugin host that already defines one plugin that shall always be executed after all plugins declared by extensions. Actually the Spring container typically returnes beans in the order they were declared, so that you could import you wildcarded config files right before declaring the default plugin. Unfortunately
243   
-the order of the beans is not contracted to be preserved for the Spring container. Thus we need a different solution.
  244 
+Declaring plugin beans sometimes it is necessary to preserve a certain order of plugins. Suppose you have a plugin host that already defines one plugin that shall always be executed after all plugins declared by extensions. Actually the Spring container typically returns beans in the order they were declared, so that you could import you wildcarded config files right before declaring the default plugin. Unfortunately the order of the beans is not contracted to be preserved for the Spring container. Thus we need a different solution.
244 245
245 246 
 Spring provides two ways to order beans. First, you can implement `Ordered` interface and implement `getOrder` to place a plugin at a certain point in the list. Secondly you can user the `@Order` annotation. For more information on ordering capabilities of Spring see the [section on this topic in the Spring reference documentation](http://static.springsource.org/spring/docs/3.1.x/javadoc-api/org/springframework/core/Ordered.html).
246 247
247 248 
 Using the Spring Plugin namespace you will get a `PluginRegistry` instance that is capable of preserving the order defined by the mentioned means. Using Spring Plugin
248   
-programatically use `OrderAwarePluginRegistry`.
  249 
+programmatically use `OrderAwarePluginRegistry`.
249 250
250 251 
 ## Metadata
251 252 
 
@@ -268,10 +269,10 @@ public interface MetadataProvider {
268 269 
 }
269 270 
 ~~~~
270 271
271   
-The `PluginMetadata` interface captures the required properties to define an identifyable plugin. This means, that implementations should ensure uniqueness through these two properties. With `SimplePluginMetadata` Spring Plugin provides a Java bean style class to capture metadata. Of course applications can and should provide extended metadata information according to their needs. The very narrow interface is only targeted at integrating the metadata concept with the `PluginRegistry` (see [the section called “PluginRegistry”](#core.plugin-registry)) without bothering developers with too much information required.
  272 
+The `PluginMetadata` interface captures the required properties to define an identifiable plugin. This means, that implementations should ensure uniqueness through these two properties. With `SimplePluginMetadata` Spring Plugin provides a Java bean style class to capture metadata. Of course applications can and should provide extended metadata information according to their needs. The very narrow interface is only targeted at integrating the metadata concept with the `PluginRegistry` (see [the section called “PluginRegistry”](#core.plugin-registry)) without bothering developers with too much information required.
272 273
273 274 
 The `MetadataProvider` interface is to be used in application plugin interfaces to indicate that they can provide metadata. To ease plugin implementation we provide
274   
-`AbstractMetadataBasedPlugin` that uses the internal metadata to implement `supports(..)` method of `Plugin`. Extending this base class plugins with metadata as selection criteria can easily be build. This way you could store the metadata in user specific configuration files and use this to select a distinct plugin specific to a given user.
  275 
+`AbstractMetadataBasedPlugin` that uses the internal metadata to implement `supports(…)` method of `Plugin`. Extending this base class plugins with metadata as selection criteria can easily be build. This way you could store the metadata in user specific configuration files and use this to select a distinct plugin specific to a given user.
275 276
276 277 
 ## Glossary
277 278

0 notes on commit 3f94160

Please sign in to comment.
Something went wrong with that request. Please try again.