File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\model\EnvironmentContributor.java.html

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2010, CloudBees, Inc.
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 * THE SOFTWARE.
23 */
24 package hudson.model;
25
26 import hudson.EnvVars;
27 import hudson.Extension;
28 import hudson.ExtensionList;
29 import hudson.ExtensionPoint;
30 import hudson.scm.SCM;
31 import jenkins.model.Jenkins;
32
33 import java.io.IOException;
34
35 /**
36 * Contributes environment variables to builds.
37 *
38 * <p>
39 * This extension point can be used to externally add environment variables. Aside from adding environment variables
40 * of the fixed name, a typical strategy is to look for specific {@link JobProperty}s and other similar configurations
41 * of {@link Job}s to compute values.
42 *
43 * <h2>Views</h2>
44 * <h4>buildEnv.groovy/.jelly</h4>
45 * <p>
46 * When Jenkins displays the help page listing all the environment variables available for a build, it does
47 * so by combining all the {@code buildEnv} views from this extension point. This view should use the &lt;t:buildEnvVar> tag
48 * to render a variable.
49 *
50 * <p>
51 * In this view, {@code it} points to {@link EnvironmentContributor} and {@code job} points to {@link Job} for which
52 * the help is being rendered.
53 *
54 * <p>
55 * Jenkins provides other extension points (such as {@link SCM}) to contribute environment variables to builds,
56 * and for those plugins, Jenkins also looks for {@code /buildEnv.groovy} and aggregates them.
57 *
58 * @author Kohsuke Kawaguchi
59 * @since 1.392
60 * @see BuildVariableContributor
61 */
62 public abstract class EnvironmentContributor implements ExtensionPoint {
63 /**
64 * Contributes environment variables used for a build.
65 *
66 * <p>
67 * This method can be called repeatedly for the same {@link Run}, thus
68 * the computation of this method needs to be efficient. If you have a time-consuming
69 * computation, one strategy is to take the hit once and then add the result as {@link InvisibleAction}
70 * to {@link Run}, then reuse those values later on.
71 *
72 * <p>
73 * This method gets invoked concurrently for multiple {@link Run}s that are being built at the same time,
74 * so it must be concurrent-safe.
75 *
76 * @param r
77 * Build that's being performed. Never null.
78 * @param envs
79 * Partially built environment variable map. Implementation of this method is expected to
80 * add additional variables here. Never null.
81 * @param listener
82 * Connected to the build console. Can be used to report errors. Never null.
83 */
84 public abstract void buildEnvironmentFor(Run r, EnvVars envs, TaskListener listener) throws IOException, InterruptedException;
85
86 /**
87 * Returns all the registered {@link EnvironmentContributor}s.
88 */
89 public static ExtensionList<EnvironmentContributor> all() {
90 return Jenkins.getInstance().getExtensionList(EnvironmentContributor.class);
91 }
92
93 /**
94 * Serves the combined list of environment variables available from this plugin.
95 *
96 * Served from "/env-vars.html"
97 */
98 @Extension
99 public static class EnvVarsHtml implements RootAction {
100 public String getIconFileName() {
101 return null;
102 }
103
104 public String getDisplayName() {
105 return null;
106 }
107
108 public String getUrlName() {
109 return "env-vars.html";
110 }
111 }
112 }
113