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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2009, Sun Microsystems, 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.tasks.BuildStep;
27 import hudson.tasks.Recorder;
28 import hudson.tasks.Builder;
29 import hudson.tasks.junit.JUnitResultArchiver;
30 import hudson.scm.SCM;
31
32 /**
33 * Provides a mechanism for synchronizing build executions in the face of concurrent builds.
34 *
35 * <p>
36 * At certain points of a build, {@link BuildStep}s and other extension points often need
37 * to refer to what happened in its earlier build. For example, a {@link SCM} check out
38 * can run concurrently, but the changelog computation requires that the check out of the
39 * earlier build has completed. Or if Hudson is sending out an e-mail, he needs to know
40 * the result of the previous build, so that he can decide an e-mail is necessary or not.
41 *
42 * <p>
43 * Check pointing is a primitive mechanism to provide this sort of synchronization.
44 * These methods can be only invoked from {@link Executor} threads.
45 *
46 * <p>
47 * Each {@link CheckPoint} instance represents unique check points. {@link CheckPoint}
48 * instances are normally created as a static instance, because two builds of the same project
49 * needs to refer to the same check point instance for synchronization to happen properly.
50 *
51 * <p>
52 * This class defines a few well-known check point instances. plugins can define
53 * their additional check points for their own use.
54 *
55 * <h2>Example</h2>
56 * <p>
57 * {@link JUnitResultArchiver} provides a good example of how a {@link Recorder} can
58 * depend on its earlier result.
59 *
60 * @author Kohsuke Kawaguchi
61 * @see BuildStep#getRequiredMonitorService()
62 * @since 1.319
63 */
64 public final class CheckPoint {
65 private final Object identity;
66 private final String internalName;
67
68 /**
69 * For advanced uses. Creates a check point that uses the given object as its identity.
70 */
71 public CheckPoint(String internalName, Object identity) {
72 this.internalName = internalName;
73 this.identity = identity;
74 }
75
76 /**
77 * @param internalName
78 * Name of this check point that's used in the logging, stack traces, debug messages, and so on.
79 * This is not displayed to users. No need for i18n.
80 */
81 public CheckPoint(String internalName) {
82 this(internalName, new Object());
83 }
84
85 @Override
86 public boolean equals(Object that) {
87 if (that == null || getClass() != that.getClass()) return false;
88 return identity== ((CheckPoint) that).identity;
89 }
90
91 @Override
92 public int hashCode() {
93 return identity.hashCode();
94 }
95
96 @Override
97 public String toString() {
98 return "Check point "+internalName;
99 }
100
101 /**
102 * Records that the execution of the build has reached to a check point, idenified
103 * by the given identifier.
104 *
105 * <p>
106 * If the successive builds are {@linkplain #block() waiting for this check point},
107 * they'll be released.
108 *
109 * <p>
110 * This method can be only called from an {@link Executor} thread.
111 */
112 public void report() {
113 Run.reportCheckpoint(this);
114 }
115
116 /**
117 * Waits until the previous build in progress reaches a check point, identified
118 * by the given identifier, or until the current executor becomes the youngest build in progress.
119 *
120 * <p>
121 * Note that "previous build in progress" should be interpreted as "previous (build in progress)" instead of
122 * "(previous build) if it's in progress". This makes a difference around builds that are aborted or
123 * failed very early without reporting the check points. Imagine the following time sequence:
124 *
125 * <ol>
126 * <li>Build #1, #2, and #3 happens around the same time
127 * <li>Build #3 waits for check point {@link JUnitResultArchiver}
128 * <li>Build #2 aborts before getting to that check point
129 * <li>Build #1 finally checks in {@link JUnitResultArchiver}
130 * </ol>
131 *
132 * <p>
133 * Using this method, build #3 correctly waits until the step 4. Because of this behavior,
134 * the {@link #report()}/{@link #block()} pair can normally
135 * be used without a try/finally block.
136 *
137 * <p>
138 * This method can be only called from an {@link Executor} thread.
139 *
140 * @throws InterruptedException
141 * If the build (represented by the calling executor thread) is aborted while it's waiting.
142 */
143 public void block() throws InterruptedException {
144 Run.waitForCheckpoint(this);
145 }
146
147 /**
148 * {@link CheckPoint} that indicates that {@link AbstractBuild#getCulprits()} is computed.
149 */
150 public static final CheckPoint CULPRITS_DETERMINED = new CheckPoint("CULPRITS_DETERMINED");
151 /**
152 * {@link CheckPoint} that indicates that the build is completed.
153 * ({@link AbstractBuild#isBuilding()}==false)
154 */
155 public static final CheckPoint COMPLETED = new CheckPoint("COMPLETED");
156 /**
157 * {@link CheckPoint} that indicates that the build has finished executing the "main" portion
158 * ({@link Builder}s in case of {@link FreeStyleProject}) and now moving on to the post-build
159 * steps.
160 */
161 public static final CheckPoint MAIN_COMPLETED = new CheckPoint("MAIN_COMPLETED");
162 }
163