From 504fbed09edd0b6cc8fbb025ed1e5127754b7654 Mon Sep 17 00:00:00 2001
From: Benjamin Bentmann <bentmann@apache.org>
Date: Fri, 4 Sep 2009 12:49:47 +0000
Subject: [PATCH] o Added API docs

git-svn-id: https://svn.apache.org/repos/asf/maven/maven-3/trunk@811372 13f79535-47bb-0310-9956-ffa450edef68
---
 .../DefaultMavenExecutionRequestPopulator.java  |  5 +++++
 .../MavenExecutionRequestPopulator.java         | 17 +++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/maven-embedder/src/main/java/org/apache/maven/embedder/execution/DefaultMavenExecutionRequestPopulator.java b/maven-embedder/src/main/java/org/apache/maven/embedder/execution/DefaultMavenExecutionRequestPopulator.java
index ed13421dac..db214fda14 100644
--- a/maven-embedder/src/main/java/org/apache/maven/embedder/execution/DefaultMavenExecutionRequestPopulator.java
+++ b/maven-embedder/src/main/java/org/apache/maven/embedder/execution/DefaultMavenExecutionRequestPopulator.java
@@ -56,6 +56,11 @@ public class DefaultMavenExecutionRequestPopulator
     public MavenExecutionRequest populateFromSettings( MavenExecutionRequest request, Settings settings )
         throws MavenEmbedderException
     {
+        if ( settings == null )
+        {
+            return request;
+        }
+
         request.setOffline( settings.isOffline() );
         
         request.setInteractiveMode( settings.isInteractiveMode() );
diff --git a/maven-embedder/src/main/java/org/apache/maven/embedder/execution/MavenExecutionRequestPopulator.java b/maven-embedder/src/main/java/org/apache/maven/embedder/execution/MavenExecutionRequestPopulator.java
index 5dfd283fb5..c185da21a6 100644
--- a/maven-embedder/src/main/java/org/apache/maven/embedder/execution/MavenExecutionRequestPopulator.java
+++ b/maven-embedder/src/main/java/org/apache/maven/embedder/execution/MavenExecutionRequestPopulator.java
@@ -31,9 +31,26 @@ import org.apache.maven.settings.Settings;
 public interface MavenExecutionRequestPopulator
 {
 
+    /**
+     * Copies the values from the given settings into the specified execution request. This method will replace any
+     * existing values in the execution request that are controlled by the settings. Hence, it is expected that this
+     * method is called on a new/empty execution request before the caller mutates it to fit its needs.
+     * 
+     * @param request The execution request to populate, must not be {@code null}.
+     * @param settings The settings to copy into the execution request, may be {@code null}.
+     * @return The populated execution request, never {@code null}.
+     * @throws MavenEmbedderException If the execution request could not be populated.
+     */
     MavenExecutionRequest populateFromSettings( MavenExecutionRequest request, Settings settings )
         throws MavenEmbedderException;
 
+    /**
+     * Injects default values like plugin groups or repositories into the specified execution request.
+     * 
+     * @param request The execution request to populate, must not be {@code null}.
+     * @return The populated execution request, never {@code null}.
+     * @throws MavenEmbedderException If the execution request could not be populated.
+     */
     MavenExecutionRequest populateDefaults( MavenExecutionRequest request )
         throws MavenEmbedderException;