Author: jdcasey
Date: Mon Sep 14 22:36:45 2009
New Revision: 814894
URL: http://svn.apache.org/viewvc?rev=814894&view=rev
Log:
Adding documentation, and some info required by modello plugin 1.1
Added:
maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/supplemental-models.apt.vm
(with props)
Modified:
maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/remote-resources.mdo
maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/supplemental-model.mdo
maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/index.apt
maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/usage.apt.vm
maven/plugins/trunk/maven-remote-resources-plugin/src/site/site.xml
Modified:
maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/remote-resources.mdo
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/remote-resources.mdo?rev=814894&r1=814893&r2=814894&view=diff
==============================================================================
---
maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/remote-resources.mdo
(original)
+++
maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/remote-resources.mdo
Mon Sep 14 22:36:45 2009
@@ -17,7 +17,10 @@
under the License.
-->
-<model>
+<model xmlns="http://modello.codehaus.org/MODELLO/1.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://modello.codehaus.org/MODELLO/1.0.0
http://modello.codehaus.org/xsd/modello-1.0.0.xsd";
+
xml.namespace="http://maven.apache.org/plugins/maven-remote-resources-plugin/remote-resources/${version}";
+
xml.schemaLocation="http://maven.apache.org/plugins/maven-remote-resources-plugin/xsd/remote-resources-${version}.xsd";>
<id>remoteResourcesBundle</id>
<name>RemoteResourcesBundle</name>
<description><![CDATA[
Modified:
maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/supplemental-model.mdo
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/supplemental-model.mdo?rev=814894&r1=814893&r2=814894&view=diff
==============================================================================
---
maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/supplemental-model.mdo
(original)
+++
maven/plugins/trunk/maven-remote-resources-plugin/src/main/mdo/supplemental-model.mdo
Mon Sep 14 22:36:45 2009
@@ -17,7 +17,10 @@
under the License.
-->
-<model>
+<model xmlns="http://modello.codehaus.org/MODELLO/1.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://modello.codehaus.org/MODELLO/1.0.0
http://modello.codehaus.org/xsd/modello-1.0.0.xsd";
+
xml.namespace="http://maven.apache.org/plugins/maven-remote-resources-plugin/supplemental-model/${version}";
+
xml.schemaLocation="http://maven.apache.org/plugins/maven-remote-resources-plugin/xsd/supplemental-model-${version}.xsd";>
<id>supplementalModel</id>
<name>SupplementalDataModel</name>
<description>Provides access to supplemental POM data models.</description>
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=814894&r1=814893&r2=814894&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
Mon Sep 14 22:36:45 2009
@@ -48,9 +48,14 @@
* Usage
General instructions on how to use the Remote Resources Plugin can be found
on the {{{./usage.html}usage page}}.
- Last but not least, users occasionally contribute
- additional examples, tips or errata to the
+ Occasionally, users also contribute their own examples, tips or errata to the
{{{http://docs.codehaus.org/display/MAVENUSER/Remote+Resources+Plugin}plugin's
wiki page}}.
+
+ If you need help using some of the more advanced features of the plugin,
check out the advanced help pages:
+
+ * {{{supplemental-models.html}Patching Bad POMs with Supplemental Models}}
+
+ []
In case you still have questions regarding the plugin's usage, please have a
look at the {{{./faq.html}FAQ}} and feel
free to contact the {{{./mail-lists.html}user mailing list}}. The posts to
the mailing list are archived and could
Added:
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=814894&view=auto
==============================================================================
---
maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/supplemental-models.apt.vm
(added)
+++
maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/supplemental-models.apt.vm
Mon Sep 14 22:36:45 2009
@@ -0,0 +1,216 @@
+ ------
+ Supplementing Missing POM Information - Maven Remote Resources Plugin
+ ------
+ John Casey
+ ------
+ 14 September 2009
+ ------
+
+~~ 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.
+
+Supplementing Missing POM Information - Maven Remote Resources Plugin
+
+ (<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
+ own, your project doesn't need to provide an exhaustive listing of all
libraries used by all
+ of your direct dependencies.
+
+ However, this approach of reusing POM metadata from your dependencies can be
inhibited by a
+ dependency POM that provides less-than-complete information about its
project. While most POMs
+ provide reasonably accurate information about their dependencies, they
sometimes leave out some
+ information critical to assembling licensing and dependency notice files.
+
+ 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.
+
+ 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.
+
+* 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
+ 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:
+
++---+
+ <dependency>
+ <groupId>org.foo</groupId>
+ <artifactId>missing-org-info</artifactId>
+ <version>1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.foo</groupId>
+ <artifactId>missing-project-url</artifactId>
+ <version>1</version>
+ </dependency>
++---+
+
+ Now imagine that your project needs to include a file in its distribution
that lists organization and
+ project URLs for each dependency, in a format like this:
+
++---+
+From: Apache Software Foundation (http://www.apache.org/)
+
+ - Commons FOO (http://commons.apache.org/foo/) org.apache.commons.foo:foo:1
+ - Commons BAR (http://commons.apache.org/bar/) org.apache.commons.bar:bar:1
++---+
+
+ However, as you try generating these licensing resources for your project,
you quickly learn that your dependencies
+ provide POMs that don't always include all the information needed by this
format. The first dependency is missing
+ all of the information provided by the <<<organization>>> element of the POM,
and the second is missing a project-
+ 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>>>,
+ would look something like this:
+
++---+
+<?xml version="1.0" encoding="UTF-8"?>
+<supplementalDataModels>
+ <supplement>
+ <project>
+ <groupId>org.foo</groupId>
+ <artifactId>missing-org-info</artifactId>
+
+ <organization>
+ <name>FOO, Inc.</name>
+ <url>http://www.foo.org/</url>
+ </organization>
+ </project>
+ </supplement>
+ <supplement>
+ <project>
+ <groupId>org.foo</groupId>
+ <artifactId>missing-project-url</artifactId>
+
+ <url>http://www.foo.org/projects/missing-project-url/</url>
+ </project>
+ </supplement>
+</supplementalDataModels>
++---+
+
+ 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>
++---+
+
+ 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>)
+
+ 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:
+ <<<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
+ 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:
+
++---+
+<?xml version="1.0" encoding="UTF-8"?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd";
+ xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.myco</groupId>
+ <artifactId>dependency-resource-supplement</artifactId>
+ <version>1</version>
+</project>
++---+
+
+ 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:
+
++---+
+|-- pom.xml
+`-- src
+ `-- main
+ `-- resources
+ `-- supplemental-models.xml
++---+
+
+ 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>
++---+
+
+ Once the supplemental-model project is released and deployed, any number of
projects can then make use of the
+ supplemental information it provides.
Propchange:
maven/plugins/trunk/maven-remote-resources-plugin/src/site/apt/supplemental-models.apt.vm
------------------------------------------------------------------------------
svn:eol-style = native
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=814894&r1=814893&r2=814894&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
Mon Sep 14 22:36:45 2009
@@ -26,7 +26,7 @@
Usage
-* Multi-Module Builds <since: 1.1>
+* Running Once in a Multi-Module Build (<Since: 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,
@@ -126,3 +126,92 @@
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.
+ 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.
+
+ To enable the filter delimiters for the format '<<<#\{expr}>>>' (Ruby-style),
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>
++---+
+
+ Notice the '<<<*>>>' character above. This denotes the dividing point
between start and end delimiter, where the actual
+ expression will be specified.
+
+ If your start and end delimiters are the same, you can use an even simpler
configuration. For example, to enable filter
+ 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>
++---+
+
+ 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.
+
+ 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>
++---+
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=814894&r1=814893&r2=814894&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 Mon Sep
14 22:36:45 2009
@@ -28,6 +28,9 @@
<item name="Introduction" href="index.html"/>
<item name="Goals" href="plugin-info.html"/>
<item name="Usage" href="usage.html"/>
+ <item name="Advanced Usage">
+ <item name="Supplemental Models" href="supplemental-models.html"/>
+ </item>
<item name="FAQ" href="faq.html"/>
</menu>
</body>
