added a SEED_JOB script variable which provides access to the seed job (#878)

Author: daspilker

docs/Home.md

@@ -32,6 +32,8 @@ Browse the Jenkins issue tracker to see any [open issues](https://issues.jenkins
  * Updated [Structs Plugin](https://github.com/jenkinsci/structs-plugin) dependency to version 1.2
  * Improved support for [[Automatically Generated DSL]]: print deprecation warnings and show deprecated methods in API
    viewer
+ * Added a `SEED_JOB` script variable which provides access to the seed job,
+   see [Job DSL Commands](Job-DSL-Commands#seed-job)
  * Removed anything that has been deprecated in 1.42, see [Migration](Migration#migrating-to-142)
 * 1.48 (June 24 2016)
  * Added option to ignore missing DSL script files or empty wildcards

docs/Job-DSL-Commands.md

@@ -293,3 +293,21 @@ The `__FILE__` variable is available in scripts only, not in any classes used by
 Job DSL scripts are executed on the Jenkins master node, but the seed job's workspace which contains the script files
 may reside on a build node. This mean that direct access to the file specified by `__FILE__` may not be possible from a
 DSL script. See [Distributed builds](https://wiki.jenkins-ci.org/display/JENKINS/Distributed+builds) for details.
+
+# Seed Job
+
+Access to the seed job is available through the `SEED_JOB` variable. The variable contains a reference to the internal
+Jenkins object that represents the seed job. The actual type of the object depends on the type of job that runs the DSL.
+For a freestyle project, the object is an instance of `hudson.model.FreeStyleProject`. See the
+[Jenkins API Documentation](http://javadoc.jenkins-ci.org/) for details.
+
+The `SEED_JOB` variable is only available in scripts, not in any classes used by a script. And it is only available
+when running in Jenkins, e.g. in the "Process Job DSLs" build step.
+
+The following example show how to apply the same quiet period for a generated job as for the seed job.
+
+```groovy
+job('example') {
+    quietPeriod(SEED_JOB.quietPeriod)
+}
+```

docs/Migration.md

@@ -1,3 +1,10 @@
+## Migrating to 1.49
+
+### JobManagement
+
+The return type of the `getParameters()` method in `javaposse.jobdsl.dsl.JobManagement` changed from
+`Map<String, String>` to `Map<String, Object>`.
+
 ## Migrating to 1.48
 
 ### Pipeline Compatibility

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

@@ -274,7 +274,7 @@ class DslScriptLoader {
             binding.setVariable('__FILE__', scriptRequest.scriptPath)
         }
 
-        jobManagement.parameters.each { String key, String value ->
+        jobManagement.parameters.each { String key, Object value ->
             LOGGER.fine("Binding ${key} to ${value}")
             binding.setVariable(key, value)
         }

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/JobManagement.groovy

@@ -126,7 +126,7 @@ interface JobManagement {
     /**
      * Map of variables that should be available to the script.
      */
-    Map<String, String> getParameters()
+    Map<String, Object> getParameters()
 
     /**
      * Logs a deprecation warning for the calling method.

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/MockJobManagement.groovy

@@ -6,7 +6,7 @@ import hudson.util.VersionNumber
  * Abstract base class for all non-Jenkins implementations of {@link JobManagement}.
  */
 abstract class MockJobManagement extends AbstractJobManagement {
-    final Map<String, String> parameters = [:]
+    final Map<String, Object> parameters = [:]
     final Map<String, List<String>> permissions = [
             'hudson.security.AuthorizationMatrixProperty': [
                     'hudson.model.Item.Delete',

job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/InterruptibleJobManagement.groovy

@@ -85,7 +85,7 @@ class InterruptibleJobManagement implements JobManagement {
     }
 
     @Override
-    Map<String, String> getParameters() {
+    Map<String, Object> getParameters() {
         delegate.parameters
     }
 

job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/JenkinsJobManagement.java

@@ -236,8 +236,12 @@ public void createOrUpdateUserContent(UserContent userContent, boolean ignoreExi
     }
 
     @Override
-    public Map<String, String> getParameters() {
-        return envVars;
+    public Map<String, Object> getParameters() {
+        Map<String, Object> result = new HashMap<String, Object>(envVars);
+        if (project != null && !result.containsKey("SEED_JOB")) {
+            result.put("SEED_JOB", project);
+        }
+        return result;
     }
 
     @Override

job-dsl-plugin/src/test/groovy/javaposse/jobdsl/plugin/JenkinsJobManagementSpec.groovy

@@ -9,6 +9,7 @@ import hudson.model.Cause
 import hudson.model.Failure
 import hudson.model.FreeStyleBuild
 import hudson.model.FreeStyleProject
+import hudson.model.Job
 import hudson.model.ListView
 import hudson.model.Run
 import hudson.model.View
@@ -47,12 +48,24 @@ class JenkinsJobManagementSpec extends Specification {
     @Rule
     JenkinsRule jenkinsRule = new JenkinsRule()
 
-    ByteArrayOutputStream buffer = new ByteArrayOutputStream()
-    Run build = Mock(Run)
-    JenkinsJobManagement jobManagement = new JenkinsJobManagement(
-            new PrintStream(buffer), [:], build, new FilePath(new File('.')), LookupStrategy.JENKINS_ROOT
-    )
-    JenkinsJobManagement testJobManagement = new JenkinsJobManagement(new PrintStream(buffer), [:], new File('.'))
+    ByteArrayOutputStream buffer
+    Job seedJob
+    Run build
+    JenkinsJobManagement jobManagement
+    JenkinsJobManagement testJobManagement
+
+    def setup() {
+        seedJob = Mock(Job)
+        build = Mock(Run)
+
+        build.parent >> seedJob
+
+        buffer = new ByteArrayOutputStream()
+        jobManagement = new JenkinsJobManagement(
+                new PrintStream(buffer), [:], build, new FilePath(new File('.')), LookupStrategy.JENKINS_ROOT
+        )
+        testJobManagement = new JenkinsJobManagement(new PrintStream(buffer), [:], new File('.'))
+    }
 
     @WithoutJenkins
     def 'createOrUpdateView without name'() {
@@ -837,6 +850,23 @@ class JenkinsJobManagementSpec extends Specification {
         project.builds.lastBuild.causes[0].shortDescription == 'Started by a Job DSL script'
     }
 
+    def 'parameters include SEED_JOB'() {
+        when:
+        Map<String, Object> parameters = jobManagement.parameters
+
+        then:
+        parameters.containsKey('SEED_JOB')
+        parameters.SEED_JOB == seedJob
+    }
+
+    def 'parameters do not include SEED_JOB for testing'() {
+        when:
+        Map<String, Object> parameters = testJobManagement.parameters
+
+        then:
+        !parameters.containsKey('SEED_JOB')
+    }
+
     private static boolean isXmlIdentical(String expected, Node actual) throws Exception {
         XMLUnit.ignoreWhitespace = true
         XMLUnit.compareXML(loadResource(expected), nodeToString(actual)).identical()