-----
 Maven Lifecycle
 -----
 The Maven Team
 -----

Maven Lifecycle

*Lifecycle Permutations

 * Single goal

   - session lifecycle[1]
     
     - dep resolution (if POM present)
     
     - dep download[2]
       
       - each downloaded dep is registered in MavenSession to track
         snapshot downloads

     - goal lifecycle
       
       - goal resolution (we assume here only one goal is resolved)[3]
       
         - download plugin for goal if necessary[2]
         
       - goal execution

+-----+

                    +------------>  goalX
                    |                |
                    |                |
                    |           is the plugin for
                    |           goalX present?
                    |                |
                    |                |
                    |         yes ---+--- no
                    |          |          |
                    |          |          v
                    |          |      download the plugin which
                    |          |      contains code for this goal
                    |          |          |
                    |          |          |
                    |          |          v
                    |          |      process the plugin descriptor
                    |          |      and cache the results
                    |          |          |
                    |          |          |
                    |          |<---------+
                    |          |
                    |          |
                    |          |
                    |          v
                    |         does goalX have any preGoals?
                    |          |
                    |   yes ---+----- no
                    |    |             |
                    |    v             |
/----------------/  | foreach(pregoal) |
|each pregoal is |  | (1)| (2)|        |
|a goal which    |  +----+    |        |
|may be in       |  |         +------->|
|another plugin  |  |                  |
/----------------/  |                  |
                    |                  v
                    |                does goalX have any prereqs?
                    |                  |
                    |           yes ---+----- no
                    |            |             |
                    |            v             |
/---------------/   |         foreach(prereq)  |
|each prereq is |   |         (1)| (2)|        |
|a goal which   |   |            |    |        |
|may be in      |   |            |    |<-------+
|another plugin |   |            |    |
/---------------/   |            |    |
                    +------------+    |
                    |                 |
                    |                 v
                    |               does goalX have any postGoals?
                    |                 |
                    |          yes ---+------ no
                    |           |              |
                    |           v              |
/---------------/   |        foreach(postgoal) |
|each postgoal  |   |        (1)| (2)|         |
|is a goal which|   +-----------+    |         |
|may be in      |                    +-------->|
|another plugin |                              |
/---------------/                              |
                                               v

/-----------------------------------------------------------------------------/
| The general form for goal resolution is:                                    |
|                                                                             |
| [ main-preGoal* ] [ prereq ]* main-goal [ main-postGoal* ]                  |
|                                                                             |
| where each goal (whether it be preGoal, prereq, goal, or postGoal) is       |
| subject to the same recursive resolution process.                           |
/-----------------------------------------------------------------------------/

+-----+                     

 * Multiple goals
 
   - session lifecycle[1]
   
     - dep resolution (if POM present)
     
     - dep download[2]
     
     - goal lifecycle (assume that multiple goals are supplied by user)
     
       - goal resolution (assume multiple goals)
       
         - download plugin for goal(s) as necessary[2]
       
       - goal execution
 
 * Implied goals (prereq, preGoal, postGoal)
 
 * Reactor with a single goal
 
 * Reactor with multiple goals

 
*Use Cases
  
  * where one goal needs to use and modify another goal
    eg jcoverage:report does jcoverage:instrument [compiler:compile], 
    then calls surefire:test (adding classpath entries and changing the test
    classes directory parameter)
    the does the report
    
  * where a goal does not require a pom.xml (pom-writer, for example).
    Here, the pom should NOT be read.

  * is there a case where a goal should in fact be executed twice in a
    session? Something like "m2 clean foo clean"
    
    - DAG (or DAG-like process) is used for goal resolution, which
      should ensure that only explicit multi-calls execute multiple
      times.

  * ability to alias a goal to a series of other goals, eg: my-goal: clean, foo, clean

*Notes
 
  [[1]] POM reading: we always attempt to read the POM but it may not be
        present because some goals don't require the presence of a POM like
        stub generation, project setup or whatever. So we can flag this state
        and throw an exception down the line if a goal in fact requires a
        project, or if there is a POM when there shouldn't be one.
    
  [[2]] Artifact downloading: all artifacts downloaded during session 
        execution should be registered in a session-scope collection of id's
        to avoid multiple download of -SNAPSHOT and other artifacts.
     
  [[3]] Goal Resolution: Involves resolving all implied goals (via prereqs, 
        pre- and post-goal decorations, and resolving/downloading any associated
        plugins. Plugin download must be a utility used by this, to ensure that
        any goals - specified or resolved - have their associated plugins 
        downloaded.