Repository: maven Updated Branches: refs/heads/master 54827e6b0 -> c2d3dec23
improved documentation Project: http://git-wip-us.apache.org/repos/asf/maven/repo Commit: http://git-wip-us.apache.org/repos/asf/maven/commit/c2d3dec2 Tree: http://git-wip-us.apache.org/repos/asf/maven/tree/c2d3dec2 Diff: http://git-wip-us.apache.org/repos/asf/maven/diff/c2d3dec2 Branch: refs/heads/master Commit: c2d3dec2306184e0a120d6209f66bbdd31e677b7 Parents: 54827e6 Author: Hervé Boutemy <hbout...@apache.org> Authored: Sun Oct 2 10:02:21 2016 +0200 Committer: Hervé Boutemy <hbout...@apache.org> Committed: Sun Oct 2 10:02:21 2016 +0200 ---------------------------------------------------------------------- maven-core/project-builder.txt | 1 - .../src/main/java/org/apache/maven/Maven.java | 3 + .../java/org/apache/maven/SessionScoped.java | 4 +- .../apache/maven/execution/MavenSession.java | 2 + .../maven/execution/ProjectDependencyGraph.java | 1 + .../org/apache/maven/graph/GraphBuilder.java | 5 + maven-core/src/site/apt/index.apt | 23 ++- .../apt/scripting-support/marmalade-support.apt | 196 ------------------- 8 files changed, 26 insertions(+), 209 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/maven/blob/c2d3dec2/maven-core/project-builder.txt ---------------------------------------------------------------------- diff --git a/maven-core/project-builder.txt b/maven-core/project-builder.txt deleted file mode 100644 index a9aab65..0000000 --- a/maven-core/project-builder.txt +++ /dev/null @@ -1 +0,0 @@ -Maven Project Builder and Maven Model Builder http://git-wip-us.apache.org/repos/asf/maven/blob/c2d3dec2/maven-core/src/main/java/org/apache/maven/Maven.java ---------------------------------------------------------------------- diff --git a/maven-core/src/main/java/org/apache/maven/Maven.java b/maven-core/src/main/java/org/apache/maven/Maven.java index 8563847..69f9fca 100644 --- a/maven-core/src/main/java/org/apache/maven/Maven.java +++ b/maven-core/src/main/java/org/apache/maven/Maven.java @@ -23,7 +23,10 @@ import org.apache.maven.execution.MavenExecutionRequest; import org.apache.maven.execution.MavenExecutionResult; /** + * The main Maven execution entry point, which will execute a full Maven execution session. + * * @author Jason van Zyl + * @see org.apache.maven.execution.MavenSession */ public interface Maven { http://git-wip-us.apache.org/repos/asf/maven/blob/c2d3dec2/maven-core/src/main/java/org/apache/maven/SessionScoped.java ---------------------------------------------------------------------- diff --git a/maven-core/src/main/java/org/apache/maven/SessionScoped.java b/maven-core/src/main/java/org/apache/maven/SessionScoped.java index 63b1eb7..7738938 100644 --- a/maven-core/src/main/java/org/apache/maven/SessionScoped.java +++ b/maven-core/src/main/java/org/apache/maven/SessionScoped.java @@ -28,8 +28,8 @@ import java.lang.annotation.Target; import com.google.inject.ScopeAnnotation; /** - * Indicates that annotated component should be instantiated before session starts and discarded after session execution - * completes. + * Indicates that annotated component should be instantiated before session execution starts + * and discarded after session execution completes. * * @author Jason van Zyl * @since 3.2.0 http://git-wip-us.apache.org/repos/asf/maven/blob/c2d3dec2/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java ---------------------------------------------------------------------- diff --git a/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java b/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java index 864c49ad..d69bbba 100644 --- a/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java +++ b/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java @@ -39,6 +39,8 @@ import org.codehaus.plexus.component.repository.exception.ComponentLookupExcepti import org.eclipse.aether.RepositorySystemSession; /** + * A Maven execution session. + * * @author Jason van Zyl */ public class MavenSession http://git-wip-us.apache.org/repos/asf/maven/blob/c2d3dec2/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java ---------------------------------------------------------------------- diff --git a/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java b/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java index 1db277d..0d5584b 100644 --- a/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java +++ b/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java @@ -27,6 +27,7 @@ import org.apache.maven.project.MavenProject; * Describes the inter-dependencies between projects in the reactor. * * @author Benjamin Bentmann + * @since 3.0-alpha */ public interface ProjectDependencyGraph { http://git-wip-us.apache.org/repos/asf/maven/blob/c2d3dec2/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java ---------------------------------------------------------------------- diff --git a/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java b/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java index fb7c4f2..0f584d9 100644 --- a/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java +++ b/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java @@ -23,6 +23,11 @@ import org.apache.maven.execution.MavenSession; import org.apache.maven.execution.ProjectDependencyGraph; import org.apache.maven.model.building.Result; +/** + * Builds the {@link ProjectDependencyGraph inter-dependencies graph} between projects in the reactor. + * + * @since 3.0-alpha + */ public interface GraphBuilder { String HINT = "graphBuilder"; http://git-wip-us.apache.org/repos/asf/maven/blob/c2d3dec2/maven-core/src/site/apt/index.apt ---------------------------------------------------------------------- diff --git a/maven-core/src/site/apt/index.apt b/maven-core/src/site/apt/index.apt index 966b57c..1e7a68e 100644 --- a/maven-core/src/site/apt/index.apt +++ b/maven-core/src/site/apt/index.apt @@ -27,14 +27,25 @@ Maven Core Maven Core classes managing the whole build process. -* Useful entry points +* Reference Documentation * {{{./lifecycles.html}lifecycles}} and {{{./default-bindings.html}plugin bindings to <<<default>>> lifecycle}}, * {{{./artifact-handlers.html}default artifact handlers}}, + * {{{./extension.html}extension descriptor}} and {{{./core-extensions.html}core extensions}}, + + * {{{/guides/mini/guide-maven-classloading.html}classloader hierarchy}} done by <<<ClassRealmManager>>> component + ({{{./apidocs/org/apache/maven/classrealm/ClassRealmManager.html}javadoc}}), + with its <<<DefaultClassRealmManager>>> implementation + ({{{./xref/org/apache/maven/classrealm/DefaultClassRealmManager.html}source}}), using + {{{https://codehaus-plexus.github.io/plexus-classworlds/}Plexus Classworlds}}, + +* Useful entry points + * <<<Maven>>> component ({{{./apidocs/org/apache/maven/Maven.html}javadoc}}), - with its <<<DefaultMaven>>> implementation ({{{./xref/org/apache/maven/DefaultMaven.html}source}}), + with its <<<DefaultMaven>>> implementation ({{{./xref/org/apache/maven/DefaultMaven.html}source}}), to drive + a full <<<MavenSession>>> execution ({{{./apidocs/org/apache/maven/execution/MavenSession.html}javadoc}} * <<<ProjectBuilder>>> component ({{{./apidocs/org/apache/maven/project/ProjectBuilder.html}javadoc}}), with its <<<DefaultProjectBuilder>>> implementation @@ -47,14 +58,6 @@ Maven Core * {{{./apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}PluginParameterExpressionEvaluator}}, used to evaluate plugin parameters values during Mojo configuration, - * {{{/guides/mini/guide-maven-classloading.html}classloader hierarchy}} done by <<<ClassRealmManager>>> component - ({{{./apidocs/org/apache/maven/classrealm/ClassRealmManager.html}javadoc}}), - with its <<<DefaultClassRealmManager>>> implementation - ({{{./xref/org/apache/maven/classrealm/DefaultClassRealmManager.html}source}}), using - {{{https://codehaus-plexus.github.io/plexus-classworlds/}Plexus Classworlds}}, - - * {{{./extension.html}extension descriptor}} and {{{./core-extensions.html}core extensions}}, - * <<<ExceptionHandler>>> component ({{{./apidocs/org/apache/maven/exception/ExceptionHandler.html}javadoc}}), with its <<<DefaultExceptionHandler>>> implementation ({{{./xref/org/apache/maven/exception/DefaultExceptionHandler.html}source}}), use to transform exception into useful end-user messages. http://git-wip-us.apache.org/repos/asf/maven/blob/c2d3dec2/maven-core/src/site/apt/scripting-support/marmalade-support.apt ---------------------------------------------------------------------- diff --git a/maven-core/src/site/apt/scripting-support/marmalade-support.apt b/maven-core/src/site/apt/scripting-support/marmalade-support.apt deleted file mode 100644 index 7a80966..0000000 --- a/maven-core/src/site/apt/scripting-support/marmalade-support.apt +++ /dev/null @@ -1,196 +0,0 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. - - --- - Marmalade Mojo Support - Notes - --- - John Casey - --- - 07-Feb-2005 - --- - -Marmalade Support - -*Abstract - - This document will track the design and implementation issues involved in - adding support to m2 for marmalade-based mojos. - -*Design Notes - - [[1]] <<Marmalade mojo descriptor specification.>> - - As in all mojo specifications, it is ideal that the descriptor for - a marmalade-based mojo be inline with the source code. This centralizes - all maintenance related to a single mojo to a single point of maintenance. - - The following is what I'm thinking as of now: - - - a marmalade-based mojo should look something like: - -+---+ - <mojo xmlns="m2:mojo" xmlns:marmalade-control="marmalade:marmalade-control" marmalade-control:el="none"> - - <metadata> - <id>mmld</id> - <name>mmldCompile</name> - <lifecyclePhase>compile</lifecyclePhase> - <description>Used to compile marmalade scripts into java beans.</description> - - <requiresDependencyResolution/> - <instantiationStrategy/> - <executionStrategy/> - - <parameters> - - <parameter> - <name>classpath</name> - <description>The compilation classpath</description> - <type>java.util.List</type> - <expression>#pom.artifacts</expression> - - <required/> - <validator/> - <default/> - - </parameter> - - </parameters> - - </metadata> - - <execute> - <!-- Do some stuff. --> - </execute> - - </mojo> -+---+ -[NOTE] All empty elements above signify optional elements, usage specification. - - [[2]] <<Marmalade mojo packager.>> - - The marmalade mojo packager will: - - [[a]] Locate all *.mmld files within the scripts directory of the project. - - The scripts directory should be tied to the script language within - the POM. Until we have multiple language support in the POM, we'll - use something like: <<<xpath(build/marmaladeSourceDirectory)>>>. - - [[b]] For each script found: - - [[i]] Execute the script with "gatherMetadata=true" in the context. - - [[ii]] Retrieve the mojo descriptor from the resulting "metadata" - variable in the context. - - [[iii]] Cache the mojo descriptor in aggregator for subsequent - output to plugin descriptor file. - - [[c]] Copy all scripts to the target directory. Preserve relative paths. - - [[d]] <<Process Disjoint:>> <Allow other mojo-descriptor collectors to - run, aggregating their descriptors in similar fashion to [b.iii] - above.> - - [[e]] Use the project's dependencies and other info to form the plugin - descriptor's header (non-mojo-specific info). - - [[f]] Use the PluginGenerator from maven-plugin-tools to generate a - META-INF/plexus/plugin.xml to the target directory. - - [[g]] Continue with lifecycle. - - This may include compilation of java helper classes, etc. and - plugin-artifact packaging, presumably via 'jar:jar' or similar. - - [[3]] <<Marmalade mojo loader.>> - - The marmalade mojo loader will: - - [[a]] Retrieve the implementation spec (this is the path of the script, - relative to the root of the plugin filesystem...jar, etc.) to - $path. - - [[b]] Use the context classloader to retrieve a reader to $path. - - [[c]] Build the ScriptBuilder corresponding to the script. - - [[d]] Create a new MarmaladeMojo instance which adapts the mojo calling - semantics to the creation/execution of a marmalade script. - - Execution involves: - - [[i]] Creating a new MarmaladeScript instance. - - [[ii]] Creating an execution context which references all I/O - from the main Maven execution thread, and embeds: - - - #request == MavenExecutionRequest - - - #response == MavenExecutionResponse - - - Any globally configured environmental constraints, such - as a global preserve-whitespace setting - - [[iii]] Execution of the script using the execution context. - - [[iv]] Export of the resulting context, minus any surviving input - variables, to the MavenExecutionResponse's out-params. - -*Implementation Issues - - [[1]] How do we make Maven smart enough to switch loader implementations based - on some sub-type of maven-plugin? - - This is important, since the default mojo loader will not be smart - enough to do the job, and embedding this behavior in that loader is not - scalable or extensible enough to accommodate future expansion into the - realms of jython, groovy, etc... - - <<UPDATE:07-FEB-2005>> - - We'll plan on using some sort of language specification in the mojo - descriptor to determine which mojo loader to use, then we'll populate - the PluginLoader/PluginManager with a map of known languages->loaders. - - [[2]] How do we make the plugin:install process smart enough to switch - generator implementations based on some sub-type of maven-plugin? - - This is closely related to [1] above. - - <<UPDATE:07-FEB-2005>> - - See update in [3]. - - [[3]] Do we want to allow mixed-bag plugin implementations? - - These might include a mix of standard-java and marmalade mojos. It - strikes me that many marmalade-based mojos may use beans/tags that are - actually adapter classes for other third-party APIs (why they wouldn't - implement everything as java mojos in this cases is beyond me). If they - have java source inside the plugin source directory, we should probably - compile it and bundle it with the plugin scripts; but what if this source - also has mojo annotations? This will have implications for [1] and [2] - above. - - <<UPDATE:07-FEB-2005>> - - We will plan on allowing this sort of implementation, and simply start - by applying all known generators which have a source directory set in - the POM (or later, have a <language/> section, maybe). At any rate, - helper classes will be allowed for script-based mojos.
