diff options
Diffstat (limited to 'framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt')
10 files changed, 1115 insertions, 0 deletions
diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/artifact-handlers.apt b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/artifact-handlers.apt new file mode 100644 index 00000000..916161bf --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/artifact-handlers.apt @@ -0,0 +1,59 @@ +~~ 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. + + --- + Default Artifact Handlers Reference + --- + Hervé Boutemy + --- + 2013-08-02 + --- + +Default Artifact Handlers Reference + + Some artifact handlers (see {{{../maven-artifact/apidocs/org/apache/maven/artifact/handler/ArtifactHandler.html} API}}) + are configured by default in <<<META-INF/plexus/artifact-handlers.xml>>>: + +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +|| type || extension || packaging || classifier || language || added to classpath || includesDependencies || +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<pom>>> | <= type> | <= type> | | none | | | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<jar>>> | <= type> | <= type> | | java | <<<true>>> | | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<maven-plugin>>> | <<<jar>>> | <= type> | | java | <<<true>>> | | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<ejb>>> | <<<jar>>> | <= type> | | java | <<<true>>> | | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<ejb3>>> | <= type> | <= type> | | java | | <<<true>>> | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<war>>> | <= type> | <= type> | | java | | <<<true>>> | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<ear>>> | <= type> | <= type> | | java | | <<<true>>> | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<rar>>> | <= type> | <= type> | | java | | <<<true>>> | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<par>>> | <= type> | <= type> | | java | | <<<true>>> | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<java-source>>> | <<<jar>>> | <= type> | <<<sources>>> | java | | | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<javadoc>>> | <<<jar>>> | <= type> | <<<javadoc>>> | java | <<<true>>> | | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<ejb-client>>> | <<<jar>>> | <<<ejb>>> | <<<client>>> | java | <<<true>>> | | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ +| <<<test-jar>>> | <<<jar>>> | <<<jar>>> | <<<tests>>> | java | <<<true>>> | | +*--------------------+------------+------------+---------------+-----------+---------------------+-----------------------+ diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/configuration-management.apt b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/configuration-management.apt new file mode 100644 index 00000000..4af0f0b1 --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/configuration-management.apt @@ -0,0 +1,139 @@ +~~ 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. + + ----- + Maven configuration management + ----- + The Maven Team + ----- + +Configuration levels in maven + + In maven configuration control happens on four differ levels: the site level, the group level, + the project level, and the user level. On the site level you can configure maven for all users + utilizing the local installation, the group level allows configuration management for all the projects + that belong to the same group, the project level allows configuration management at + the project level, and the user level allows users to override settings on + the site level, group level and project level. + +* Site configuration + + At the site level all configuration is achieved by tweaking the the various files that + are available in the ${maven.home}/site-configuration directory + ++-----+ +${maven.home} + | + +--- maven.properties ++-----+ + +* Group configuration + + As far as properties go for an entire build the maven.properties could be placed at + the top of the group but I'm not really sure how this might work. There could probably + also be a directory for plugins.xml and maven.properties. + +* Project configuration + + At the project level all configuration is achieved by tweaking the POM. One of the differences between + maven 1.x and 2.x is that all project parameterization occurs in the POM and not from properties + files. + + For many of the more advanced features in Maven2 it is critical that POMs be available in the local repository. + Features like transitive dependencies and the new parent specification mechanism. The problem we run into is + that currently we have information about a project scattered across the project.xml and the + various properties files. What needs to be done is to encapsulate all of this in the POM. + + Typically users parameterize the use of plugins, or have custom values like ${user.name} + for use in elements like the <developerConnection/>. It would be idea if we + could encapsulate everything we need about the project in the POM including + plugin parameters and anything else. + + We once had a document that Vincent and I agreed upon and I was about to + implement it and then I disappeared for 8 months so it never came to pass. + + So I guess it's important to figure out what people are using propeties + files for and see if we can't incorporate it all into the POM. Or if we do + have properties file (something I would like to avoid) say they don't + contribute in any meaningful way to information in the POM. For example a + properties file could be used the specify $ so it can be interpolated in + <developerConnection/> but you couldn't use a properties file to specify the + version of your project say. Anyway, food for thought to begin with. + + - elements that are critical for pom dissemination + - those that are used locally by the user like <developerConnection/> + +* User configuration + + User configuration which is utilized site wide are controlled with the ${user.home}/.m2/maven.properties. + + User configuration which is utilized at the project level are controlled with the + ${project.home}/maven.properties file. + +Plugin configuration + + The configuration of plugins is of the same form as the maven {{{plugin-descriptors}plugin descriptors}} + themselves: + ++-----+ +<plugins> + <plugin> + <id>xdoc</id> + <version>1.0</version> + <parameters> + <parameter> + <name>theme</name> + <value>classic</value> + </parameter> + </parameters> + </plugin> +</plugins> ++-----+ + +Unified source directory + + Unified source directory structure that is analagous to the repository + itself. This way locations of intermediary artifacts of a build would be + in a known location. This would also help with developer setup i.e. getting + new developers up and running. They could run a maven command and have all + their source trees set up in the same way as their collegues. + + here's what I do currently in the netbeans part of the mevenide project to + find the relevant subprojects/sibling projects. I check if the user has + defined the maven.multiproject.includes property in any of his properties + files for the current project. if yes. then I'm able to find projects that + can be offered to be opened together with the current project. + problems with the current solution are: + 1. information is duplicate. once in POM's dependencies and once in the + maven.multiproject.includes property. + 2. it works without problems only for projects with relative paths, eg. from + one CVS repository.. for projects from multiple SCM repositories it's harder + to maintain the same relative links on all developer computers. + not sure the unified source directory structure addresses this issue. + + Properties + + maven.user.config.dir (system,default=${user.home}/.m2) + maven.home (system,user,default=${user.home}/m2) + maven.repo.local (system,user,default=${maven.user.config.dir}/repository) + + We need to define what happens in the when things are not setup correctly + + o ~/.m2 directory does not exist + o ~/.m2/maven.properties does not exist + o if they once existed but now to do not exist + o what the installer will take care of of what we can recover from diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/default-bindings.apt.vm b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/default-bindings.apt.vm new file mode 100644 index 00000000..02d6c4a9 --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/default-bindings.apt.vm @@ -0,0 +1,67 @@ +~~ 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. + + --- + Plugin Bindings for Default Lifecycle Reference + --- + Hervé Boutemy + --- + 2013-08-02 + --- + +Plugin Bindings for <<<default>>> Lifecycle Reference + + The {{{./lifecycles.html}<<<default>>> lifecycle}} is defined without any plugin binding; plugin bindings are defined separately + in <<<META-INF/plexus/default-bindings.xml>>> because they are specific for each packaging: + +%{toc|fromDepth=2} + +* Plugin bindings for <<<pom>>> packaging + +%{snippet|id=pom-lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/default-bindings.xml} + +* Plugin bindings for <<<jar>>> packaging + +%{snippet|id=jar-lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/default-bindings.xml} + +* Plugin bindings for <<<ejb>>> packaging + +%{snippet|id=ejb-lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/default-bindings.xml} + +* Plugin bindings for <<<ejb3>>> packaging + +%{snippet|id=ejb3-lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/default-bindings.xml} + +* Plugin bindings for <<<maven-plugin>>> packaging + +%{snippet|id=maven-plugin-lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/default-bindings.xml} + +* Plugin bindings for <<<war>>> packaging + +%{snippet|id=war-lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/default-bindings.xml} + +* Plugin bindings for <<<ear>>> packaging + +%{snippet|id=ear-lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/default-bindings.xml} + +* Plugin bindings for <<<rar>>> packaging + +%{snippet|id=rar-lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/default-bindings.xml} + +* Plugin bindings for <<<par>>> packaging + +%{snippet|id=par-lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/default-bindings.xml} diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/getting-to-container-configured-mojos.apt b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/getting-to-container-configured-mojos.apt new file mode 100644 index 00000000..1c4a487d --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/getting-to-container-configured-mojos.apt @@ -0,0 +1,102 @@ +~~ 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. + + --- + Getting to Plexus-configured Mojos + --- + John Casey + --- + 29-April-2005 + +Abstract + + We're moving toward integrating mojos as first-class plexus components, while + at the same time avoiding introducing required plexus dependencies into the + mojo development model. + + In order to really achieve this, we need mojo configurations (which are + provided both in terms of static expressions that are just looked up, and + in terms of user-provided configuration from system properties or the POM). + If these mojos are to be first-class components, the configuration from these + various sources must be consolidated and injected using the container. + + Currently, mojo configuration is done externally to the container, in the + DefaultPluginManager in the maven-core API. In order to get from here to + there, we need to do several things to add capability to the default + configuration of plexus. This document will detail those changes. + +Container Enhancements + +* ExpressionEvaluator + + Currently, the expression evaluator used to resolve configuration values + is the DefaultExpressionEvaluator, which is a local variable within the + implementation of the BasicComponentConfigurator. This ExpressionEvaluator + simply returns the expression itself as the resolved value, which adds + very little value to the container. Things like ${project.build.resources} + are not resolved, and result in a type mismatch for the member injection. + + We need a replacement for DefaultExpressionEvaluator that is capable of + traversing an object graph and extracting Object values, not just Strings. + +* ComponentConfigurator + + Currently, the container uses BasicComponentConfigurator, to configure + components. This wouldn't be a problem, except for the local instance of + DefaultExpressionEvaluator used within. See the above discussion for more + on why this evaluator is bad. We need to provide either an alternative + implementation under a different roleHint, or else replace the + BasicComponentConfigurator. + +* Other + + We may need to define a new lifecycle/phase to contextualize a mojo right + before it's used, and reset it's state afterward. Up to now, the approach + of most plexus components has been to avoid instance state like the plague. + With the current parameter passing model of mojos, this will not be possible, + particularly when we move mojos to a singleton instantiation model, and then + run a reactorized project...the successive calls may leave behind configuration + artifacts from invocation to invocation. + +Maven Modifications + +* DefaultPluginManager + + s/getMojoConfiguration()/getConfiguration()/g + + That should re-enable usage of mojo configuration. Ideally, we won't need any + of the code that references this method, since the container should provide + some way of recontextualizing the mojo, and all we would need to do is inject + POM configuration via the lookup method or something. + +* PluginDescriptorBuilder + + s/getMojoConfiguration()/getConfiguration()/g + + That should be all there is to it. + +* MojoDescriptor + + Remove set/getMojoConfiguration(..), as it will become obsolete. + +* MavenSession + + We may need to enable the context injection here, since this will be + instantiated per-project. If we always inject the same context parameters, + and are careful to inject nulls where things are missing, we should be + able to minimize reconfiguration artifacts injected from basic parameters. + diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/index.apt b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/index.apt new file mode 100644 index 00000000..f6c26fde --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/index.apt @@ -0,0 +1,77 @@ +~~ 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. + + ----- + Introduction + ----- + Hervé Boutemy + ----- + 2013-07-27 + ----- + +Maven Core + + Maven Core classes managing the whole build process. + +* Useful entry points + + * {{{./lifecycles.html}lifecycles}} and {{{./default-bindings.html}plugin bindings to <<<default>>> lifecycle}}, + + * {{{./artifact-handlers.html}default artifact handlers}}, + + * <<<Maven>>> component ({{{./apidocs/org/apache/maven/Maven.html}javadoc}}), + with its <<<DefaultMaven>>> implementation ({{{./xref/org/apache/maven/DefaultMaven.html}source}}), + + * <<<ProjectBuilder>>> component ({{{./apidocs/org/apache/maven/project/ProjectBuilder.html}javadoc}}), + with its <<<DefaultProjectBuilder>>> implementation + ({{{./xref/org/apache/maven/project/DefaultProjectBuilder.html}source}}), + + * <<<MavenPluginManager>>> component ({{{./apidocs/org/apache/maven/plugin/MavenPluginManager.html}javadoc}}), + with its <<<DefaultMavenPluginManager>>> implementation + ({{{./xref/org/apache/maven/plugin/internal/DefaultMavenPluginManager.html}source}}), + + * {{{./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 + {{{http://plexus.codehaus.org/plexus-classworlds/}Plexus Classworlds}}, + + * {{{./extension.html}extension descriptor}}, + + * <<<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. + +* Toolchains + + * {{{./toolchains.html}Toolchains descriptor reference}}, + + * public API for toolchains-aware plugins: <<<ToolchainManager>>> component ({{{./apidocs/org/apache/maven/toolchain/ToolchainManager.html}javadoc}}) + with its <<<DefaultToolchainManager>>> implementation ({{{./xref/org/apache/maven/toolchain/DefaultToolchainManager.html}source}}), + to get selected <<<Toolchain>>> ({{{./apidocs/org/apache/maven/toolchain/Toolchain.html}javadoc}}) instance, + + * internal <<<ToolchainManagerPrivate>>> component ({{{./apidocs/org/apache/maven/toolchain/ToolchainManagerPrivate.html}javadoc}}) + with its <<<DefaultToolchainManagerPrivate>>> implementation ({{{./xref/org/apache/maven/toolchain/DefaultToolchainManagerPrivate.html}source}}), + to manage toolchain selection, + + * internal JDK toolchain implementation: <<<JavaToolchain>>> interface ({{{./apidocs/org/apache/maven/toolchain/java/JavaToolchain.html}javadoc}}), + with its <<<JavaToolchainImpl>>> implementation + ({{{./xref/org/apache/maven/toolchain/java/JavaToolchainImpl.html}source}}) and <<<JavaToolchainFactory>>> + factory ({{{./xref/org/apache/maven/toolchain/java/JavaToolchainFactory.html}source}}). diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/inheritance.apt b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/inheritance.apt new file mode 100644 index 00000000..dbf0e2c2 --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/inheritance.apt @@ -0,0 +1,100 @@ +~~ 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. + + ----- + Inheritance in Maven + ----- + The Maven Team + ----- + +Inheritance in Maven + + In order the understand how inheritance works in Maven there are a few notions that you must be familiar with: + + * The maven super model + + * how parent poms are processed + + * the order in which elements in the POM are overridden + + * minimum element-set for a valid project pom + + +Maven super model + + Inheritance is recursive in Maven but there is a special model which is the implicit super parent in the lineage + of models you may specify: + + all of the models that you specify are collected to produce a lineage and then the super model is place at + the top of that lineage to provide default values. + + The super model is where we place all the values which we believe to be standard, values that can be shared and + utilized across all your maven projects. + ++-----+ + m0 <- m1 <- m2 ++-----+ + + which is transformed into + ++-----+ + super model <- m0 <- m1 <- m2 ++-----+ + ++-----+ +<project> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId></groupId> + <artifactId></artifactId> + <version></version> + </parent> +</project> ++-----+ + +Extending the POM in the future + + In order to anticipate changes in the structure of the POM as new releases of + maven occur, the maven inheritance model must be pinned against a particular + modelVersion. This is required so that a change from modelVersion 4.0.0 to + 4.1.0 doesn't cause compatibility problems with users who have not upgraded + their projects. It also allows for a certain amount of legacy support into the + future. Therefore, we should rename this file from pom.xml in the maven-core + jarfile to pom-4.0.0.xml (and successive revisions to the base pom made to + accommodate changes in the model will be named accordingly - 4.0.1, 4.0.2, ...). + +Minimum Element-Set for a Project POM + + In order to furnish a basic set of information which we need to distinguish one + project from another, maven requires a minimum set of elements to be specified + in each project's pom.xml. + + - [modelVersion] tells maven which version of the object model this project + is compliant with (to support future legacy concerns) + + - [artifactId] tells maven what the artifact name is for this particular + project. Each project should have a distinct artifactId. + + - [version] tells maven what release of this artifact we're trying to produce. + The fact that a project has a distinct pom.xml should indicate a separate + release cycle that is also distinct to that project, so a concrete version + declaration is required. + + - [name] tells maven what the user-friendly name of this project is. The name + element is similar to artifactId in that it is a unique descriptor for + this and only this project, and therefore should be concretely defined. + diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/lifecycles.apt.vm b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/lifecycles.apt.vm new file mode 100644 index 00000000..3e47bc90 --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/lifecycles.apt.vm @@ -0,0 +1,49 @@ +~~ 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. + + ----- + Lifecycles Reference + ----- + Hervé Boutemy + ----- + 2013-08-02 + ----- + +Lifecycles Reference + + Maven defines 3 lifecycles in <<<META-INF/plexus/components.xml>>>: + +%{toc|fromDepth=2} + +* <<<default>>> Lifecycle + + <<<default>>> lifecycle is defined <<without>> any associated plugin. + Plugin bindings for this lifecycle are {{{./default-bindings.html}defined separately for every packaging}}: + +%{snippet|id=lifecycle|file=${project.basedir}/src/main/resources/META-INF/plexus/components.xml} + +* <<<clean>>> Lifecycle + + <<<clean>>> lifecycle is defined directly with its plugin bindings. + +%{snippet|id=clean|file=${project.basedir}/src/main/resources/META-INF/plexus/components.xml} + +* <<<site>>> Lifecycle + + <<<site>>> lifecycle is defined directly with its plugin bindings. + +%{snippet|id=site|file=${project.basedir}/src/main/resources/META-INF/plexus/components.xml} diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/offline-mode.apt b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/offline-mode.apt new file mode 100644 index 00000000..faec70fa --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/offline-mode.apt @@ -0,0 +1,269 @@ +~~ 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. + + --- + Offline Mode Design + --- + John Casey + --- + 08-April-2005 + --- + +Offline Mode Design + +* UPDATE: 18-April-2005 + + We cannot take the approach outlined below of detecting which remote + repositories are "really" offline, since offline mode is more of a behavior, + and this will lead to counter-intuitive results. A different feature may exist + unimplemented, which is to detect when the network is down and provide better + feedback for that case. However, when offline mode is declared, nothing + earmarked as remote should be accessed, regardless of whether it is actually + a physically local resource. + + NOTE: One side-effect of this design change is that all offline-mode code can + be isolated to maven-core, maven-plugin-descriptor, and [possibly] + maven-artifact. Usage of maven-wagon will be determined by an offline-aware + manager. + +* Assumptions: What is Offline? + + For the purposes of determining the areas sensitive to offline status, + it is definitely useful to define what the offline state really means. + + [[1]] This is obvious, but the network/internet is unavailable. + + [[2]] Localhost (127.0.0.1) may also be unavailable if the whole + network stack is offline. + + [[3]] "Remote" repositories referenced using the file:// protocol may + be available. However, if that file:// url references a + file-share, as in the case of an NFS or SMB mount, that will + be unavailable. + + So, offline mode has several implications, some of which may not be + altogether obvious: + + * Localhost may be unavailable. Therefore, even locally installed + server processes which work by conversing over a port may fail. + + * Not all "remote" repositories will fail. Specifically, if the remote + repo uses the file:// protocol, and it doesn't refer to a shared + filesystem, it will continue to be available. + + The question remaining is: Which level of offline mode will we support? It + seems reasonable to assume that users will be able to tell when localhost is + not active (in most cases, localhost should be available, even if the rest of + the network is not). Therefore, let's concentrate on the state where no + network <beyond localhost> exists, and leave the more extreme state to users + to diagnose and correct as necessary. + +* Why is Offline Mode Important? + + Offline mode is essential for breaking the requirement that m2 operate in a + network-connected environment. It means legitimizing a development environment + in which there is no network connection, and providing a robust m2 service + offering in such circumstances. Introduction of offline mode allows m2 to + anticipate the inevitable network failures that accompany being physically + disconnected from the network, and adjust it's behavior accordingly. + + It is more than simply understanding that m2 cannot go and check for the + latest version of some snapshot artifact. If m2 is offline, SCM operations + cannot succeed; no artifact downloads can take place, regardless of whether + they are snapshot versions; artifact deployment cannot take place; certain + types of tests cannot be setup, since the container used to run them cannot be + reached or started. + + All of these operations will produce their own unique errors in the absence of + a coordinated offline strategy. In addition, efforts to unite these failing + behaviors behind a consistent user interface is much, much more difficult if + the system can't tell whether it has access to the network required by these + operations. + + Offline mode really means anticipating a lack of network connectivity, and as + a result turning off certain services provided by m2 and providing a coherent + way of predicting and reporting when network-related failures will take place. + It means warning users that since the network is missing, certain features and + operations will be unavailable, rather than simply waiting for those + operations to fail, then trying to help users decipher the error messages they + get as a result. + +* Implications for Resolution + +** Dependency Resolution + + This one is obvious...we only have access to the repositories using + the file:// protocol and living on a truly local filesystem when + offline. + +** Plugin Resolution + + This is similar to dependency resolution. Plugin repositories not + using file:// or not residing on a local (not shared) filesystem will + be unavailable. + + +* Implications for Mojo Execution + +** Deployment mojos + + The concept of deployment is dependent on the availability of a some + remote repository. Just as above, if that repository is not using + file:// (which is highly likely to be the case), or the repository is + not on a local filesystem, deployment will fail when offline. + +** Testing mojos + + This can be a problem if the tests are more than simple unit tests; + that is, if they require configuration of a server process, and + subsequent testing in-container. + + Since we're only going to concern ourselves with states where localhost is + still active, we only need to worry about this case when the server container + is <<not>> installed on localhost. This allows the popular pattern of starting + a server container in-JVM, running tests against it, and shutting it down. + +** SCM mojos + + See below for discussion on SCM-related operations. Any mojo which + carries out some analysis or other interaction with a SCM system + will likely be unavailable when in offline mode. + + +* Implications for Subsystems + +** Maven-Wagon + + Parts of Wagon will continue to function normally. These include: + + * The file wagon, provided the referenced location is on a local + filesystem. + + It is not possible to determine whether a file-based location will + be available except on a case-by-case basis (or a root-url by + root-url basis). We may want to move the offline sensitivity entirely to + Maven-Artifact, below, so we can be smarter about testing filesystem-based + repositories, etc. + + * If not otherwise specified, all other wagons are assumed to be + remote-only, and are therefore sensitive to offline mode. + +** Maven-Artifact + + This is wholly dependent on Maven-Wagon, above. + + We could possibly use a flag on a particular Wagon to see whether it supports + offline mode, and then test to see if the file-based basedir for an aritfact + repository works...if it doesn't work, we can mark that repository offline... + + OTOH, all offline-mode checks can probably be run from Wagon-based APIs. + +** Maven-SCM + + In all but trivial examples, SCM operations cannot complete without + having access to the versioning server. Therefore, it is assumed that + any SCM-related activity will be unavailable when m2 is in offline + mode. + +** Maven-Core + + We'll examine the different parts of maven-core on a case-by-case + basis, below: + +*** DefaultLifecycleExecutor + + When binding goals to the project's configured lifecycle, each mojo + descriptor should declare whether it requires online/offline status. + This value should be a java.lang.Boolean, so it can implement 3VL + (three value logic: yes, no, don't-care). The requiresOnline + field in the mojo descriptor has the following semantics: + + [true] Online status is required for this mojo to function + correctly. + + [false] <<(Default)>> Either status is acceptable for the mojo to + execute. It doesn't care. + + The majority of mojos will leave the requiresOnline == false, + since online/offline status will be irrelevant, provided they have + access to their required artifacts and other classpath elements. In the case + of required artifacts and other classpath elemtents, this is assumed by the + mojo API to be in a correct state, and will be handled by the Wagon + modifications. + + +* Implementation Notes + +** Accessibility of offline status + + Offline status should be indicated in the MavenSettings instance, since it + can conceivably be set from either the settings.xml or the command-line. + + In the event the '-o' switch is the impetus for setting offline mode, this + should result in modification of the active profile in the MavenSettings + instance, just as definition of the active profile from the command-line + should result in similar modification. This object is not meant to be + static within the build process, but rather to be setup as an aggregation of + all settings-related information passed into the system. + +** Control over downloads + + Find the control point for m2 using maven-wagon. At this point, inject + a offline status parameter which is used when retrieving the specific Wagon. + + If <<<offline == true>>>: + + * If the wagon is not bound to "file://", then ignore the request and print + a debug message. + + * If the wagon is bound to "file://" then: + + Retrieve the file or base-url file to be "downloaded". + + * If the file (or more usefully, the base-url file) exists, proceed. + + * If the file (or base-url file) doesn't exist, assume that this location + is part of a file-share. Ignore the request and print a debug message + as above. + +** Control over mojos in the lifecycle + + When binding a mojo to the project's lifecycle instance, check the mojo + descriptor's requiredConnectivity field. + + * If <<<(offline == true) && (requiresOnline != true)>>>, bind + the mojo to the lifecycle. + + In this case, the client is <<offline>>, and the mojo does not require + online status. + + * If <<<(offline == false) && (requiresOnline == true)>>>, bind + the mojo to the lifecycle. + + In this case, the client is <<online>>, and the mojo either requires + <<online>> status, or else doesn't care. + + * Otherwise, don't bind the mojo. Log a debug message to indicate that it is + sensitive the the online state of the application, and that this state is + currently wrong for execution. + + <<NOTE:>> Do we want to fail when we cannot bind a mojo to the lifecycle + because of offline/online status? That would probably indicate that the user + was trying to do something they cannot succeed at for now...so we probably + should throw an exception in this case. + + diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/plugin-execution-isolation.apt b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/plugin-execution-isolation.apt new file mode 100644 index 00000000..983a9fde --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/plugin-execution-isolation.apt @@ -0,0 +1,57 @@ +~~ 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. + + ----- + Maven plugins + ----- + The Maven Team + ----- + +Maven plugin execution isolation + + Maven2 takes advantage of Plexus' ability to execute a component using a + ClassWorlds ClassRealm that is populated with the JAR containing the + component in question and all of its dependencies. Using ClassWorlds + notation for realms we have the following: + ++-----+ + [plexus.core] + ^ + | + [plexus.core.maven] + ^ ^ + | | +[plugin0] [plugin1] ++-----+ + + The <<<plexus.core>>> realm contains the resources required to run any + plexus application; The <<<plexus.core.maven>>> realm contains all of the + resources required to run Maven. Each subseqent plugin realm contains the + JAR plugin as well as its dependencies. The realms noted above are setup + in a hierachical structure where the resources in the parent realms are + available but the <<realm is searched first before a search is made in + the parent realm>>. + + Plugins are guaranteed to be provided the resources found in + <<<plexus.core>>> and <<<plexus.core.maven>>> realms at run-time if required. + Plugins can state compile-time dependencies on any of the resources found in + the core realms listed above and these dependencies will be included in the + plugin descriptor that is generated but when running within Maven these + resources will be filtered out. In other words these resources will not + be added the realm created for the plugins execution as they are provided + in the parent realms. + diff --git a/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/scripting-support/marmalade-support.apt b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/scripting-support/marmalade-support.apt new file mode 100644 index 00000000..7a809662 --- /dev/null +++ b/framework/src/maven/apache-maven-3.3.3/maven-core/src/site/apt/scripting-support/marmalade-support.apt @@ -0,0 +1,196 @@ +~~ 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. |