You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sc...@apache.org on 2017/01/25 22:42:09 UTC
[25/34] maven git commit: improved documentation
improved documentation
Project: http://git-wip-us.apache.org/repos/asf/maven/repo
Commit: http://git-wip-us.apache.org/repos/asf/maven/commit/512fa6a4
Tree: http://git-wip-us.apache.org/repos/asf/maven/tree/512fa6a4
Diff: http://git-wip-us.apache.org/repos/asf/maven/diff/512fa6a4
Branch: refs/heads/MNG-5958-IT
Commit: 512fa6a45b73663ed5b5e0e896539d1084da36f3
Parents: 0b684af
Author: Herv� Boutemy <hb...@apache.org>
Authored: Sun Oct 2 10:02:21 2016 +0200
Committer: Herv� Boutemy <hb...@apache.org>
Committed: Wed Jan 25 00:07:55 2017 +0100
----------------------------------------------------------------------
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/512fa6a4/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/512fa6a4/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/512fa6a4/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/512fa6a4/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/512fa6a4/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/512fa6a4/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/512fa6a4/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/512fa6a4/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.