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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi
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.slaves;
25
26 import hudson.ExtensionPoint;
27 import hudson.Extension;
28 import hudson.DescriptorExtensionList;
29 import hudson.slaves.NodeProvisioner.PlannedNode;
30 import hudson.model.Describable;
31 import jenkins.model.Jenkins;
32 import hudson.model.Node;
33 import hudson.model.AbstractModelObject;
34 import hudson.model.Label;
35 import hudson.model.Descriptor;
36 import hudson.security.ACL;
37 import hudson.security.AccessControlled;
38 import hudson.security.Permission;
39 import hudson.util.DescriptorList;
40
41 import java.util.Collection;
42
43 /**
44 * Creates {@link Node}s to dynamically expand/shrink the slaves attached to Hudson.
45 *
46 * <p>
47 * Put another way, this class encapsulates different communication protocols
48 * needed to start a new slave programmatically.
49 *
50 * @author Kohsuke Kawaguchi
51 * @see NodeProvisioner
52 * @see AbstractCloudImpl
53 */
54 public abstract class Cloud extends AbstractModelObject implements ExtensionPoint, Describable<Cloud>, AccessControlled {
55
56 /**
57 * Uniquely identifies this {@link Cloud} instance among other instances in {@link jenkins.model.Jenkins#clouds}.
58 */
59 public final String name;
60
61 protected Cloud(String name) {
62 this.name = name;
63 }
64
65 public String getDisplayName() {
66 return name;
67 }
68
69 public String getSearchUrl() {
70 return "cloud/"+name;
71 }
72
73 public ACL getACL() {
74 return Jenkins.getInstance().getAuthorizationStrategy().getACL(this);
75 }
76
77 public final void checkPermission(Permission permission) {
78 getACL().checkPermission(permission);
79 }
80
81 public final boolean hasPermission(Permission permission) {
82 return getACL().hasPermission(permission);
83 }
84
85 /**
86 * Provisions new {@link Node}s from this cloud.
87 *
88 * <p>
89 * {@link NodeProvisioner} performs a trend analysis on the load,
90 * and when it determines that it <b>really</b> needs to bring up
91 * additional nodes, this method is invoked.
92 *
93 * <p>
94 * The implementation of this method asynchronously starts
95 * node provisioning.
96 *
97 * @param label
98 * The label that indicates what kind of nodes are needed now.
99 * Newly launched node needs to have this label.
100 * Only those {@link Label}s that this instance returned true
101 * from the {@link #canProvision(Label)} method will be passed here.
102 * This parameter is null if Hudson needs to provision a new {@link Node}
103 * for jobs that don't have any tie to any label.
104 * @param excessWorkload
105 * Number of total executors needed to meet the current demand.
106 * Always >= 1. For example, if this is 3, the implementation
107 * should launch 3 slaves with 1 executor each, or 1 slave with
108 * 3 executors, etc.
109 * @return
110 * {@link PlannedNode}s that represent asynchronous {@link Node}
111 * provisioning operations. Can be empty but must not be null.
112 * {@link NodeProvisioner} will be responsible for adding the resulting {@link Node}s
113 * into Hudson via {@link jenkins.model.Jenkins#addNode(Node)}, so a {@link Cloud} implementation
114 * just needs to return {@link PlannedNode}s that each contain an object that implements {@link Future}.
115 * When the {@link Future} has completed its work, {@link Future#get} will be called to obtain the
116 * provisioned {@link Node} object.
117 */
118 public abstract Collection<PlannedNode> provision(Label label, int excessWorkload);
119
120 /**
121 * Returns true if this cloud is capable of provisioning new nodes for the given label.
122 */
123 public abstract boolean canProvision(Label label);
124
125 public Descriptor<Cloud> getDescriptor() {
126 return Jenkins.getInstance().getDescriptorOrDie(getClass());
127 }
128
129 /**
130 * All registered {@link Cloud} implementations.
131 *
132 * @deprecated as of 1.286
133 * Use {@link #all()} for read access, and {@link Extension} for registration.
134 */
135 public static final DescriptorList<Cloud> ALL = new DescriptorList<Cloud>(Cloud.class);
136
137 /**
138 * Returns all the registered {@link Cloud} descriptors.
139 */
140 public static DescriptorExtensionList<Cloud,Descriptor<Cloud>> all() {
141 return Jenkins.getInstance().<Cloud,Descriptor<Cloud>>getDescriptorList(Cloud.class);
142 }
143
144 /**
145 * Permission constant to control mutation operations on {@link Cloud}.
146 *
147 * This includes provisioning a new node, as well as removing it.
148 */
149 public static final Permission PROVISION = Jenkins.ADMINISTER;
150 }
151