o adding john's plugin tool refactoring document

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@170139 13f79535-47bb-0310-9956-ffa450edef68

maven-site/src/site/apt/proposals/plugin-tool-refactoring.apt

@@ -0,0 +1,66 @@
+  ---
+  Refactoring Proposal: Accommodating Generators for Multiple Plugin Types
+  ---
+  John Casey
+  ---
+  09-Feb-2005
+  ---
+  
+*Abstract
+
+  Propose changing the structure of maven-plugin-tools to accommodate multiple
+  plugin languages and their needs during the descriptor, etc. generation 
+  process. Details below.
+  
+*Refactor Details
+
+  [[1]] Move the existing project (maven-plugin-tools) to 
+        <<<maven-plugin-tools/maven-plugin-tools-java>>>. Adjust dependencies on 
+        this library accordingly within maven-components.
+        
+  [[2]] Create other plugin-tools libraries to accommodate generation needs for
+        other languages, as needed.
+        
+        The first use-case of this is the descriptor generator for 
+        marmalade-based mojos. Since we don't want the "normal" plugin tools
+        to depend on marmalade, etc. we need to make the concept of plugin-tools
+        abstract, and provide a concrete implementation for the java language, 
+        as well as marmalade.
+        
+  [[3]] Create plugin-tools root pom if needed for inheriting common values...
+  
+        I don't anticipate needing this initially, but if there is some question
+        of consistency wrt this, we can certainly provide one.
+        
+  [[4]] Create common API for use in all generator libraries. This will define
+        the interface for a mojo descriptor (and other) generator. Therefore, it
+        will require splitting the responsibility of the old PluginDescriptorGenerator
+        from what is to be the maven-plugin-tools-java library into two pieces:
+        
+        - Section covered by the AbstractGenerator code will be the complete new
+          generator for java. It will probably be further abstracted as an 
+          interface for other language implementations to follow, and then itself
+          made into a concrete, instantiable implementation. The interface will
+          define the new Reader/Source role of this class, used to produce
+          MojoDescriptor instances from the project source files.
+          
+        - Specifics handled by the PluginDescriptorGenerator (and others) will
+          be factored into the common API, and generalized as a Writer/Sink role, 
+          used to generate one or more derivative files from the MojoDescriptors
+          discovered by the set of Reader/Sources. 
+          
+        Once this split is accomplished, an additional class will be created to
+        act as a managing component for all generators registered in plexus. It
+        will require a mapping of Source-language->Source-instance where each 
+        Source is a plexus component. Unless/until we have some smarter way of 
+        specifying a plugin language as a means of singling out one Source for 
+        the project, this manager component will simply iterate through all 
+        Source instances, collect the MojoDescriptors from each, wrap them in 
+        MavenMojoDescriptors with the component-factory specified == to the 
+        Source language, and aggregate the resulting MavenMojoDescriptors in 
+        some Collection.
+        
+        Finally, the Source manager returns the aggregated result of all Sources
+        to the calling mojo. The mojo will be responsible for digesting the
+        MavenMojoDescriptors into the requisite files.
+