Merge pull request #400 from daspilker/maven-context

Refactoring of MavenContext and LocalRepositoryLocation

Author: daspilker

docs/Home.md

@@ -17,6 +17,7 @@ Have a look at the [Jenkins Job DSL Gradle example](https://github.com/sheehan/j
 
 ## Release Notes
 * 1.31 (unreleased)
+ * The enum argument of `localRepository` for the Maven job and context has changed, see [[Migration]]
 * 1.30 (March 08 2015)
  * Added support for [Custom Tools Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Custom+Tools+Plugin)
  * Added support for [Flaky Test Handler Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Flaky+Test+Handler+Plugin)

docs/Job-reference.md

@@ -757,10 +757,12 @@ Refers to the pull down box in the UI to select which installation of Maven to u
 localRepository(LocalRepositoryLocation location)
 ```
 
-LocalRepositoryLocation is available as two enums, injected into the script. Their names are LocalToExecutor and LocalToWorkspace, they can be used like this:
+Possible values for `localRepository` are `LocalRepositoryLocation.LOCAL_TO_WORKSPACE` and
+`LocalRepositoryLocation.LOCAL_TO_EXECUTOR`. The `LocalToWorkspace` and `LocalToExecutor` values are deprecated since
+1.31.
 
 ```groovy
-localRepository(LocalToWorkspace)
+localRepository(LocalRepositoryLocation.LOCAL_TO_WORKSPACE)
 ```
 
 (Since 1.17)
@@ -2290,7 +2292,7 @@ maven {                                               // since 1.20; all methods
     goals(String goals)                               // the goals to run, multiple calls will be accumulated
     rootPOM(String fileName)                          // path to the POM
     mavenOpts(String options)                         // JVM options, multiple calls will be accumulated
-    localRepository(LocalRepositoryLocation location) // can be either LocalToWorkspace or LocalToExecutor (default)
+    localRepository(LocalRepositoryLocation location) // defaults to LocalRepositoryLocation.LOCAL_TO_EXECUTOR
     mavenInstallation(String name)                    // name of the Maven installation to use
     properties(Map properties)                        // since 1.21; add (system)-properties
     property(String key, String value)                // since 1.21; add a (system)-property
@@ -2303,6 +2305,10 @@ Runs Apache Maven. Configure block is handed `hudson.tasks.Maven`. The
 [Config File Provider Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Config+File+Provider+Plugin) is required to
 use `providedSettings`.
 
+Possible values for `localRepository` are `LocalRepositoryLocation.LOCAL_TO_WORKSPACE` and
+`LocalRepositoryLocation.LOCAL_TO_EXECUTOR`. The `LocalToWorkspace` and `LocalToExecutor` values are deprecated since
+1.31.
+
 Examples:
 
 ```groovy

docs/Migration.md

@@ -1,3 +1,41 @@
+## Migrating to 1.31
+
+### Local Maven Repository Location
+
+The `localRepository` method with a `javaposse.jobdsl.dsl.helpers.common.MavenContext.LocalRepositoryLocation` argument
+has been [[deprecated|Deprecation-Policy]] and replaced by a method with a
+`javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation` argument. The values of the enum have been renamed from camel
+case to upper case to follow the naming convention for enum values. The new enum is implicitly imported, but not with
+star import as the new deprecated variant.
+
+DSL prior to 1.31
+```groovy
+mavenJob {
+    localRepository(LocalToWorkspace)
+}
+job {
+    steps {
+        maven {
+            localRepository(LocalToWorkspace)
+        }
+    }
+}
+```
+
+DSL since 1.31
+```groovy
+mavenJob {
+    localRepository(LocalRepositoryLocation.LOCAL_TO_WORKSPACE)
+}
+job {
+    steps {
+        maven {
+            localRepository(LocalRepositoryLocation.LOCAL_TO_WORKSPACE)
+        }
+    }
+}
+```
+
 ## Migrating to 1.30
 
 ### Factory and Name Methods

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/DslScriptLoader.java

@@ -194,6 +194,7 @@ private static CompilerConfiguration createCompilerConfiguration(JobManagement j
         icz.addImports("javaposse.jobdsl.dsl.views.jobfilter.RegexMatchValue");
         icz.addImports("javaposse.jobdsl.dsl.helpers.scm.SvnCheckoutStrategy");
         icz.addImports("javaposse.jobdsl.dsl.helpers.scm.SvnDepth");
+        icz.addImports("javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation");
         config.addCompilationCustomizers(icz);
 
         GrabDeprecationTransformation grabDeprecationTransformation = new GrabDeprecationTransformation(jobManagement);

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/LocalRepositoryLocation.groovy

@@ -0,0 +1,12 @@
+package javaposse.jobdsl.dsl.helpers
+
+enum LocalRepositoryLocation {
+    LOCAL_TO_EXECUTOR('hudson.maven.local_repo.PerExecutorLocalRepositoryLocator'),
+    LOCAL_TO_WORKSPACE('hudson.maven.local_repo.PerJobLocalRepositoryLocator')
+
+    final String type
+
+    LocalRepositoryLocation(String type) {
+        this.type = type
+    }
+}

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/common/MavenContext.groovy

@@ -2,53 +2,17 @@ package javaposse.jobdsl.dsl.helpers.common
 
 import javaposse.jobdsl.dsl.Context
 
+@Deprecated
 interface MavenContext extends Context {
-    /**
-     * Specifies the path to the root POM.
-     * @param rootPOM path to the root POM
-     */
-    void rootPOM(String rootPOM)
-
-    /**
-     * Specifies the goals to execute.
-     * @param goals the goals to execute
-     */
-    void goals(String goals)
-
-    /**
-     * Specifies the JVM options needed when launching Maven as an external process.
-     * @param mavenOpts JVM options needed when launching Maven
-     */
-    void mavenOpts(String mavenOpts)
-
-    /**
-     * <localRepository class="hudson.maven.local_repo.PerJobLocalRepositoryLocator"/>
-     *
-     * Set to use isolated local Maven repositories.
-     * @param location the local repository to use for isolation
-     */
-    void localRepository(LocalRepositoryLocation location)
-
-    /**
-     * Specifies the Maven installation for executing this step or job
-     * @param name name of the Maven installation to use
-     */
-    void mavenInstallation(String name)
-
-    /**
-     * Specifies the managed Maven settings to be used.
-     * @param settings name of the managed Maven settings
-     */
-    void providedSettings(String settings)
-
+    @Deprecated
     enum LocalRepositoryLocation {
-        LocalToExecutor('hudson.maven.local_repo.PerExecutorLocalRepositoryLocator'),
-        LocalToWorkspace('hudson.maven.local_repo.PerJobLocalRepositoryLocator')
+        LocalToExecutor(javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation.LOCAL_TO_EXECUTOR),
+        LocalToWorkspace(javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation.LOCAL_TO_WORKSPACE)
 
-        String type
+        final javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation location
 
-        LocalRepositoryLocation(String type) {
-            this.type = type
+        LocalRepositoryLocation(javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation location) {
+            this.location = location
         }
     }
 }

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/step/MavenContext.groovy

@@ -2,10 +2,11 @@ package javaposse.jobdsl.dsl.helpers.step
 
 import com.google.common.base.Preconditions
 import javaposse.jobdsl.dsl.ConfigFileType
+import javaposse.jobdsl.dsl.Context
 import javaposse.jobdsl.dsl.JobManagement
-import javaposse.jobdsl.dsl.helpers.common.MavenContext.LocalRepositoryLocation
+import javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation
 
-class MavenContext implements javaposse.jobdsl.dsl.helpers.common.MavenContext {
+class MavenContext implements Context {
     private final JobManagement jobManagement
 
     String rootPOM
@@ -21,32 +22,56 @@ class MavenContext implements javaposse.jobdsl.dsl.helpers.common.MavenContext {
         this.jobManagement = jobManagement
     }
 
-    @Override
+    /**
+     * Specifies the path to the root POM.
+     * @param rootPOM path to the root POM
+     */
     void rootPOM(String rootPOM) {
         this.rootPOM = rootPOM
     }
 
-    @Override
+    /**
+     * Specifies the goals to execute.
+     * @param goals the goals to execute
+     */
     void goals(String goals) {
         this.goals << goals
     }
 
-    @Override
+    /**
+     * Specifies the JVM options needed when launching Maven as an external process.
+     * @param mavenOpts JVM options needed when launching Maven
+     */
     void mavenOpts(String mavenOpts) {
         this.mavenOpts << mavenOpts
     }
 
-    @Override
+    @Deprecated
+    void localRepository(javaposse.jobdsl.dsl.helpers.common.MavenContext.LocalRepositoryLocation location) {
+        jobManagement.logDeprecationWarning()
+        this.localRepositoryLocation = location.location
+    }
+
+    /**
+     * Set to use isolated local Maven repositories.
+     * @param location the local repository to use for isolation
+     */
     void localRepository(LocalRepositoryLocation location) {
         this.localRepositoryLocation = location
     }
 
-    @Override
+    /**
+     * Specifies the Maven installation for executing this step or job
+     * @param name name of the Maven installation to use
+     */
     void mavenInstallation(String name) {
         this.mavenInstallation = name
     }
 
-    @Override
+    /**
+     * Specifies the managed Maven settings to be used.
+     * @param settings name of the managed Maven settings
+     */
     void providedSettings(String settingsName) {
         String settingsId = jobManagement.getConfigFileId(ConfigFileType.MavenSettings, settingsName)
         Preconditions.checkNotNull settingsId, "Managed Maven settings with name '${settingsName}' not found"

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/step/StepContext.groovy

@@ -10,7 +10,7 @@ import javaposse.jobdsl.dsl.WithXmlAction
 import javaposse.jobdsl.dsl.helpers.common.DownstreamContext
 
 import static com.google.common.base.Strings.isNullOrEmpty
-import static javaposse.jobdsl.dsl.helpers.common.MavenContext.LocalRepositoryLocation.LocalToWorkspace
+import static javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation.LOCAL_TO_WORKSPACE
 
 class StepContext implements Context {
     private static final List<String> VALID_CONTINUATION_CONDITIONS = ['SUCCESSFUL', 'UNSTABLE', 'COMPLETED']
@@ -369,7 +369,7 @@ class StepContext implements Context {
             if (mavenContext.rootPOM) {
                 pom mavenContext.rootPOM
             }
-            usePrivateRepository mavenContext.localRepositoryLocation == LocalToWorkspace ? 'true' : 'false'
+            usePrivateRepository mavenContext.localRepositoryLocation == LOCAL_TO_WORKSPACE
             if (mavenContext.providedSettingsId) {
                 settings(class: 'org.jenkinsci.plugins.configfiles.maven.job.MvnSettingsProvider') {
                     settingsConfigId(mavenContext.providedSettingsId)

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/jobs/MavenJob.groovy

@@ -6,6 +6,7 @@ import javaposse.jobdsl.dsl.DslContext
 import javaposse.jobdsl.dsl.Job
 import javaposse.jobdsl.dsl.JobManagement
 import javaposse.jobdsl.dsl.WithXmlAction
+import javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation
 import javaposse.jobdsl.dsl.helpers.common.MavenContext
 import javaposse.jobdsl.dsl.helpers.step.StepContext
 import javaposse.jobdsl.dsl.helpers.triggers.MavenTriggerContext
@@ -132,7 +133,22 @@ class MavenJob extends Job {
      * Set to use isolated local Maven repositories.
      * @param location the local repository to use for isolation
      */
+    @Deprecated
     void localRepository(MavenContext.LocalRepositoryLocation location) {
+        jobManagement.logDeprecationWarning()
+
+        Preconditions.checkNotNull(location, 'localRepository can not be null')
+
+        localRepository(location.location)
+    }
+
+    /**
+     * <localRepository class="hudson.maven.local_repo.PerJobLocalRepositoryLocator"/>
+     *
+     * Set to use isolated local Maven repositories.
+     * @param location the local repository to use for isolation
+     */
+    void localRepository(LocalRepositoryLocation location) {
         Preconditions.checkNotNull(location, 'localRepository can not be null')
 
         withXmlActions << WithXmlAction.create { Node project ->

job-dsl-core/src/test/groovy/javaposse/jobdsl/dsl/helpers/step/StepContextSpec.groovy

@@ -3,6 +3,7 @@ package javaposse.jobdsl.dsl.helpers.step
 import hudson.util.VersionNumber
 import javaposse.jobdsl.dsl.ConfigFileType
 import javaposse.jobdsl.dsl.JobManagement
+import javaposse.jobdsl.dsl.helpers.LocalRepositoryLocation
 import spock.lang.Specification
 import spock.lang.Unroll
 
@@ -299,7 +300,7 @@ class StepContextSpec extends Specification {
             goals('install')
             mavenOpts('-Xms256m')
             mavenOpts('-Xmx512m')
-            localRepository(LocalToWorkspace)
+            localRepository(LocalRepositoryLocation.LOCAL_TO_WORKSPACE)
             mavenInstallation('Maven 3.0.5')
             properties skipTests: true, other: 'some'
             property 'evenAnother', 'One'
@@ -317,7 +318,7 @@ class StepContextSpec extends Specification {
         mavenStep.targets[0].value() == 'clean install'
         mavenStep.pom[0].value() == 'module-a/pom.xml'
         mavenStep.jvmOptions[0].value() == '-Xms256m -Xmx512m'
-        mavenStep.usePrivateRepository[0].value() == 'true'
+        mavenStep.usePrivateRepository[0].value() == true
         mavenStep.mavenName[0].value() == 'Maven 3.0.5'
         mavenStep.settingsConfigId[0].value() == 'foo-bar'
         mavenStep.properties[0].value() == 'skipTests=true\nother=some\nevenAnother=One'
@@ -336,10 +337,24 @@ class StepContextSpec extends Specification {
         mavenStep.children().size() == 4
         mavenStep.targets[0].value() == ''
         mavenStep.jvmOptions[0].value() == ''
-        mavenStep.usePrivateRepository[0].value() == 'false'
+        mavenStep.usePrivateRepository[0].value() == false
         mavenStep.mavenName[0].value() == '(Default)'
     }
 
+    def 'call maven method with deprecated options'() {
+        when:
+        context.maven {
+            localRepository(LocalToWorkspace)
+        }
+
+        then:
+        with(context.stepNodes[0]) {
+            name() == 'hudson.tasks.Maven'
+            children().size() == 4
+            usePrivateRepository[0].value() == true
+        }
+    }
+
     def 'call maven method with unknown provided settings'() {
         setup:
         String settingsName = 'lalala'
@@ -373,7 +388,7 @@ class StepContextSpec extends Specification {
             children().size() == 5
             targets[0].value() == ''
             jvmOptions[0].value() == ''
-            usePrivateRepository[0].value() == 'false'
+            usePrivateRepository[0].value() == false
             mavenName[0].value() == '(Default)'
             settings[0].attribute('class') == 'org.jenkinsci.plugins.configfiles.maven.job.MvnSettingsProvider'
             settings[0].children().size() == 1