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

  ---
  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.