You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by de...@apache.org on 2011/01/09 11:14:13 UTC
svn commit: r1056900 - in
/maven/plugins/trunk/maven-remote-resources-plugin: pom.xml
src/site/apt/index.apt src/site/apt/supplemental-models.apt.vm
src/site/apt/usage.apt.vm src/site/fml/faq.fml src/site/site.xml
Author: dennisl
Date: Sun Jan 9 10:14:13 2011
New Revision: 1056900
URL: http://svn.apache.org/viewvc?rev=1056900&view=rev
Log:
o Improve the site.
Modified:
maven/plugins/trunk/maven-remote-resources-plugin/pom.xml
maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/index.apt
maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/supplemental-models.apt.vm
maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/usage.apt.vm
maven/plugins/trunk/maven-remote-resources-plugin/src/site/fml/faq.fml
maven/plugins/trunk/maven-remote-resources-plugin/src/site/site.xml
Modified: maven/plugins/trunk/maven-remote-resources-plugin/pom.xml
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-remote-resources-plugin/pom.xml?rev=1056900&r1=1056899&r2=1056900&view=diff
==============================================================================
--- maven/plugins/trunk/maven-remote-resources-plugin/pom.xml (original)
+++ maven/plugins/trunk/maven-remote-resources-plugin/pom.xml Sun Jan 9 10:14:13 2011
@@ -38,7 +38,7 @@ under the License.
a remote repository. The primary use case being satisfied is the consistent
inclusion of common resources in a large set of projects. Maven projects at
Apache use this plug-in to satisfy licensing requirements at Apache where
- each project much include license and notice files for each release.
+ each project must include license and notice files for each release.
</description>
<prerequisites>
@@ -207,7 +207,7 @@ under the License.
<version>1.1</version>
<executions>
<execution>
- <id>site-docs</id>
+ <id>site-docs-supplemental-models</id>
<phase>pre-site</phase>
<goals>
<goal>xdoc</goal>
@@ -221,7 +221,7 @@ under the License.
</configuration>
</execution>
<execution>
- <id>site-docs-supplement</id>
+ <id>site-docs-remote-resources</id>
<phase>pre-site</phase>
<goals>
<goal>xdoc</goal>
@@ -305,9 +305,9 @@ under the License.
<goal>test</goal>
</goals>
<configuration>
- <includes>
- <include>**/IT*.java</include>
- </includes>
+ <includes>
+ <include>**/IT*.java</include>
+ </includes>
<systemProperties>
<property>
<!-- Pass this through to the tests (if set!) to have them pick the right repository -->
@@ -315,14 +315,14 @@ under the License.
<value>${project.build.directory}/it-repo</value>
</property>
</systemProperties>
- </configuration>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </pluginManagement>
-
- <plugins>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+
+ <plugins>
<plugin>
<artifactId>maven-invoker-plugin</artifactId>
<version>1.4</version>
Modified: maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/index.apt?rev=1056900&r1=1056899&r2=1056900&view=diff
==============================================================================
--- maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/index.apt (original)
+++ maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/index.apt Sun Jan 9 10:14:13 2011
@@ -3,7 +3,7 @@
------
Jason van Zyl
------
- 27 November 2006
+ 2011-01-09
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -26,7 +26,7 @@
Maven Remote Resources Plugin
This plugin is used to retrieve JARs of resources from remote repositories,
- processes those resources, and incorporate them into JARs you build with
+ process those resources, and incorporate them into JARs you build with
Maven. A very common use-case is the need to package certain resources in a
consistent way across your organization: at Apache it is required that every
JAR produced contains a copy of the Apache license and a notice file that
Modified: maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/supplemental-models.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/supplemental-models.apt.vm?rev=1056900&r1=1056899&r2=1056900&view=diff
==============================================================================
--- maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/supplemental-models.apt.vm (original)
+++ maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/supplemental-models.apt.vm Sun Jan 9 10:14:13 2011
@@ -1,9 +1,9 @@
------
- Supplementing Missing POM Information - Maven Remote Resources Plugin
+ Supplementing Missing POM Information
------
John Casey
------
- 14 September 2009
+ 2011-01-09
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -23,14 +23,14 @@
~~ specific language governing permissions and limitations
~~ under the License.
-Supplementing Missing POM Information - Maven Remote Resources Plugin
+Supplementing Missing POM Information
+
+ <<Note:>> This feature was added in version 1.0-alpha-5.
- (<Since 1.0-alpha-5>)
-
One of Maven's great strengths is that it allows you, the user, to build directly on the work of
others with minimal effort. For instance, by adding five lines (or less) to your POM, you can
declare a dependency on someone else's library, and instruct Maven to use that library during
- the build for your own project. Since the library's jar is usually accompanied by a POM of its
+ the build for your own project. Since the library's JAR is usually accompanied by a POM of its
own, your project doesn't need to provide an exhaustive listing of all libraries used by all
of your direct dependencies.
@@ -42,21 +42,22 @@ Supplementing Missing POM Information -
For example, the templates used by many Apache distributions assemble a listing of project
dependencies according to their organization name (and URL), along with the URL each project's
website. When dependency POMs are missing this information, the dependency notice file
- that the remote-resources plugin renders can be invalid.
+ that the Remote Resources Plugin renders can be invalid.
To compensate for incomplete dependency POMs, you can use the supplemental models support, introduced
- to the remote-resources plugin in version 1.0-alpha-5, and improved in version 1.1.
-
+ to the Remote Resources Plugin in version 1.0-alpha-5, and improved in version 1.1.
+
+
* Fixing Incomplete POMs: Using Supplemental Models
For those cases where your project's dependencies don't list organization name, organization URL,
- project URL, or whatever other metadata you require for you legal notice files, the remote-resources
- plugin allows you to configure a series of supplemental models. These models consist of one or more
+ project URL, or whatever other metadata you require for you legal notice files, the Remote Resources
+ Plugin allows you to configure a series of supplemental models. These models consist of one or more
model files, each of which contains one or more POM fragments that can be merged into existing
dependency POMs to supplement the metadata provided there. The plugin uses the key <<<groupId:artifactId>>>
to match each supplemental model with the dependency POM into which it should be merged.
- For example, imagine your project's POM declared the following two dependencies:
+ For example, imagine that your project's POM has declared the following two dependencies:
+---+
<dependency>
@@ -87,7 +88,7 @@ From: Apache Software Foundation (http:/
specific URL (the <<<url>>> element of the POM).
To fix these omissions for the purposes of resource generation, we can simply provide a supplemental-model file that
- contains the missing information. The file, located in <<<src/main/appended-resources/supplemental-models.xml>>>,
+ contains the missing information. The file, located at <<<src/main/appended-resources/supplemental-models.xml>>>,
would look something like this:
+---+
@@ -115,43 +116,44 @@ From: Apache Software Foundation (http:/
</supplementalDataModels>
+---+
- Finally, we tell the remote-resources plugin to use the new supplemental-model file:
+ Finally, we tell the Remote Resources Plugin to use the new supplemental-model file:
+---+
-<plugin>
- <artifactId>maven-remote-resources-plugin</artifactId>
- <version>${project.version}</version>
- [...]
-
- <executions>
- <execution>
- <id>process-remote-resources</id>
- <goals>
- <goal>process</goal>
- </goals>
- <configuration>
- <supplementalModels>
- <supplementalModel>supplemental-models.xml</supplementalModel>
- </supplementalModels>
- [...]
- </configuration>
- </execution>
- </executions>
-</plugin>
+ <plugin>
+ <artifactId>maven-remote-resources-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <id>process-remote-resources</id>
+ <goals>
+ <goal>process</goal>
+ </goals>
+ <configuration>
+ <supplementalModels>
+ <supplementalModel>supplemental-models.xml</supplementalModel>
+ </supplementalModels>
+ [...]
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+---+
After re-running the project build, the supplemental information we provided will be merged with the metadata
from the dependency POMs, providing enough information to complete the dependencies listing.
-* Publishing and Reusing Supplemental Models (<Since 1.1>)
+
+* Publishing and Reusing Supplemental Models
+
+ <<Note:>> This feature was added in version 1.1.
The configuration above is fine for single projects that need to address deficiencies in their dependencies'
metadata. But what happens when your organization wants to use these same deficient dependencies across multiple
projects? The configuration we just examined cannot handle reuse of supplemental-model files.
- To address this shortcoming, version 1.1 of the remote-resources plugin introduces a new parameter:
+ To address this shortcoming, version 1.1 of the Remote Resources Plugin introduces a new parameter:
<<<supplementalModelArtifacts>>>. When combined with the <<<supplementalModels>>> parameter used above, this new
- parameter allows the remote-resources plugin to resolve artifacts containing supplemental model information, then
+ parameter allows the Remote Resources Plugin to resolve artifacts containing supplemental model information, then
search those artifacts for the paths given in the <<<supplementalModels>>> listing.
To make the supplemental models above reusable using this mechanism, we first publish them in their own project:
@@ -169,7 +171,7 @@ From: Apache Software Foundation (http:/
</project>
+---+
- Note that this is just a simple, unadorned jar artifact. We then move the above POM and supplemental-models.xml file
+ Note that this is just a simple, unadorned JAR artifact. We then move the above POM and <<<supplemental-models.xml>>> file
into a separate project directory structure:
+---+
@@ -180,37 +182,35 @@ From: Apache Software Foundation (http:/
`-- supplemental-models.xml
+---+
- Once we install this new project, we can reference it from the configuration for the remote-resources plugin,
+ Once we install this new project, we can reference it from the configuration for the Remote Resources Plugin,
like this:
+---+
-<plugin>
- <artifactId>maven-remote-resources-plugin</artifactId>
- <version>${project.version}</version>
- [...]
-
- <executions>
- <execution>
- <id>process-remote-resources</id>
- <goals>
- <goal>process</goal>
- </goals>
- <configuration>
- <!-- reference the supplemental-model artifact from above. -->
- <supplementalModelArtifacts>
- <supplementalModelArtifact>org.myco:dependency-resource-supplement:1</supplementalModelArtifact>
- </supplementalModelArtifacts>
-
- <!-- specify the path, relative to the jar root, where the supplemental model file is located -->
- <supplementalModels>
- <supplementalModel>supplemental-models.xml</supplementalModel>
- </supplementalModels>
- [...]
- </configuration>
- </execution>
- </executions>
-</plugin>
+ <plugin>
+ <artifactId>maven-remote-resources-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <id>process-remote-resources</id>
+ <goals>
+ <goal>process</goal>
+ </goals>
+ <configuration>
+ <!-- Reference the supplemental-model artifact from above -->
+ <supplementalModelArtifacts>
+ <supplementalModelArtifact>org.myco:dependency-resource-supplement:1</supplementalModelArtifact>
+ </supplementalModelArtifacts>
+
+ <!-- Specify the path, relative to the JAR root, where the supplemental model file is located -->
+ <supplementalModels>
+ <supplementalModel>supplemental-models.xml</supplementalModel>
+ </supplementalModels>
+ [...]
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+---+
- Once the supplemental-model project is released and deployed, any number of projects can then make use of the
+ Once the <<<supplemental-model>>> project is released and deployed, any number of projects can then make use of the
supplemental information it provides.
Modified: maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/usage.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/usage.apt.vm?rev=1056900&r1=1056899&r2=1056900&view=diff
==============================================================================
--- maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/usage.apt.vm (original)
+++ maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/usage.apt.vm Sun Jan 9 10:14:13 2011
@@ -4,7 +4,7 @@
Jason van Zyl
John Casey
------
- 27 November 2006
+ 2011-01-09
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -26,19 +26,21 @@
Usage
-* Running Once in a Multi-Module Build (<Since: 1.1>)
+* Running Once in a Multi-Module Build
+
+ <<Note:>> This feature was added in version 1.1.
In many cases, an application build consists of multiple Maven modules, but you only need to
include the license files, dependencies listing, etc. once for the entire application. Of course,
in such cases, the dependencies listing needs to aggregate all dependencies of all modules.
- To accomplish this, you can use the new <<<runOnlyAtExecutionRoot>>> parameter when you configure
- the Remote-Resources plugin in your application parent POM. This parameter limits execution of the
- Remote-Resources plugin to the root directory in which the build was run. In most cases, the
+ To accomplish this, you can use the <<<runOnlyAtExecutionRoot>>> parameter when you configure
+ the Remote Resources Plugin in your application parent POM. This parameter limits execution of the
+ Remote Resources Plugin to the root directory in which the build was run. In most cases, the
application's distribution archives will be created at this top directory, so this is a natural
location into which licensing and dependency information should be generated.
- To run the Remote-Resources plugin only in the execution root, use the following:
+ To run the Remote Resources Plugin only in the execution root, use the following:
+---+
<plugin>
@@ -61,6 +63,7 @@ Usage
</plugin>
+---+
+
* How to Create a Resource Bundle
To turn on the bundle resource manifest generation you need to configure the plugin as follows:
@@ -88,9 +91,10 @@ Usage
</project>
-------------------
- This will trigger the scanning of your <<<${basedir}/src/main/resources>>> directory and create the
+ This will trigger the scanning of that project's <<<${basedir}/src/main/resources>>> directory and create the
<<<${basedir}/target/classes/META-INF/maven/remote-resources.xml>>> manifest file.
-
+
+
* How to Use Remote Resource Bundles
To use remote resource bundles you need to configure the plugin as follows:
@@ -106,6 +110,7 @@ Usage
<version>${project.version}</version>
<executions>
<execution>
+ <id>process-remote-resources</id>
<goals>
<goal>process</goal>
</goals>
@@ -126,10 +131,13 @@ Usage
This will retrieve the <<<apache-jar-resource-bundle-1.0.jar>>> from the remote repositories
specified in your POM, process each resource in the bundle and deposit them in your projects
<<<${basedir}/target/classes>>> directory.
-
-* Specifying Delimiters for Filterable Expressions (<Since 1.1>)
- By default, the remote-resources plugin supports expressions specified using either the '<<<$\{expr}>>>' or '<<<@expr@>>>' format.
+
+* Specifying Delimiters for Filterable Expressions
+
+ <<Note:>> This feature was added in version 1.1.
+
+ By default, the Remote Resources Plugin supports expressions specified using either the '<<<$\{expr}>>>' or '<<<@expr@>>>' format.
However, at times it may be more convenient to use a different set of filter delimiters. By configuring the
<<<filterDelimiters>>> and <<<useDefaultFilterDelimiters>>> parameters, you have a high degree of control over the
filtering process.
@@ -138,26 +146,24 @@ Usage
configuration:
+---+
-<plugin>
- <artifactId>maven-remote-resources-plugin</artifactId>
- <version>${project.version}</version>
- [...]
-
- <executions>
- <execution>
- <id>process-remote-resources</id>
- <goals>
- <goal>process</goal>
- </goals>
- <configuration>
- <filterDelimiters>
- <filterDelimiter>#{*}</filterDelimiter>
- </filterDelimiters>
- [...]
- </configuration>
- </execution>
- </executions>
-</plugin>
+ <plugin>
+ <artifactId>maven-remote-resources-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <id>process-remote-resources</id>
+ <goals>
+ <goal>process</goal>
+ </goals>
+ <configuration>
+ <filterDelimiters>
+ <filterDelimiter>#{*}</filterDelimiter>
+ </filterDelimiters>
+ [...]
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+---+
Notice the '<<<*>>>' character above. This denotes the dividing point between start and end delimiter, where the actual
@@ -167,51 +173,47 @@ Usage
delimiters for the format '<<<#expr#>>>', add the following to your plugin configuration:
+---+
-<plugin>
- <artifactId>maven-remote-resources-plugin</artifactId>
- <version>${project.version}</version>
- [...]
-
- <executions>
- <execution>
- <id>process-remote-resources</id>
- <goals>
- <goal>process</goal>
- </goals>
- <configuration>
- <filterDelimiters>
- <filterDelimiter>#</filterDelimiter>
- </filterDelimiters>
- [...]
- </configuration>
- </execution>
- </executions>
-</plugin>
+ <plugin>
+ <artifactId>maven-remote-resources-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <id>process-remote-resources</id>
+ <goals>
+ <goal>process</goal>
+ </goals>
+ <configuration>
+ <filterDelimiters>
+ <filterDelimiter>#</filterDelimiter>
+ </filterDelimiters>
+ [...]
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+---+
When the filter processor executes and notices this delimiter specification missing a '<<<*>>>' character, it will simply
- assume the provided delimiter will be used as the start <and> end delimiter for an expression.
+ assume the provided delimiter will be used as both the start <and> end delimiter for an expression.
All of the above assumes that you still want the ability to use '<<<$\{expr}>>>' and '<<<@expr@>>>' delimiters. However, in
cases where this would cause trouble, you can disable these default delimiters as follows:
+---+
-<plugin>
- <artifactId>maven-remote-resources-plugin</artifactId>
- <version>${project.version}</version>
- [...]
-
- <executions>
- <execution>
- <id>process-remote-resources</id>
- <goals>
- <goal>process</goal>
- </goals>
- <configuration>
- <useDefaultFilterDelimiters>false</useDefaultFilterDelimiters>
- [...]
- </configuration>
- </execution>
- </executions>
-</plugin>
+ <plugin>
+ <artifactId>maven-remote-resources-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <id>process-remote-resources</id>
+ <goals>
+ <goal>process</goal>
+ </goals>
+ <configuration>
+ <useDefaultFilterDelimiters>false</useDefaultFilterDelimiters>
+ [...]
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+---+
Modified: maven/plugins/trunk/maven-remote-resources-plugin/src/site/fml/faq.fml
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-remote-resources-plugin/src/site/fml/faq.fml?rev=1056900&r1=1056899&r2=1056900&view=diff
==============================================================================
--- maven/plugins/trunk/maven-remote-resources-plugin/src/site/fml/faq.fml (original)
+++ maven/plugins/trunk/maven-remote-resources-plugin/src/site/fml/faq.fml Sun Jan 9 10:14:13 2011
@@ -38,7 +38,7 @@ under the License.
</answer>
</faq>
<faq id="question2">
- <question>The generated files have a lot of missing information. Looking at the poms from
+ <question>The generated files have a lot of missing information. Looking at the POMs from
the dependencies, the information isn't there either. What can I do?</question>
<answer>
<p>
@@ -75,9 +75,9 @@ under the License.
</supplement>
</supplementalDataModels>]]>
</source>
- That location for that file can then be configured in the
- <code>supplementalModels</code> configuration element for the process mojo. The
- supplemental information is merged into the information provided from the repository.
+ That location of that file can then be configured with the
+ <code>supplementalModels</code> configuration element for the <code>process</code> goal. The
+ supplemental information is merged with the information provided from the repository.
</li>
</ol>
</answer>
Modified: maven/plugins/trunk/maven-remote-resources-plugin/src/site/site.xml
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-remote-resources-plugin/src/site/site.xml?rev=1056900&r1=1056899&r2=1056900&view=diff
==============================================================================
--- maven/plugins/trunk/maven-remote-resources-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-remote-resources-plugin/src/site/site.xml Sun Jan 9 10:14:13 2011
@@ -21,8 +21,7 @@ under the License.
<project xmlns="http://maven.apache.org/DECORATION/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd"
- name="Maven Remote Resources plugin">
+ xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
<body>
<menu name="Overview">
<item name="Introduction" href="index.html"/>