File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\util\DescriptorList.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.util;
25
26 import hudson.Extension;
27 import hudson.ExtensionList;
28 import hudson.model.Describable;
29 import hudson.model.Descriptor;
30 import hudson.model.Descriptor.FormException;
31 import jenkins.model.Jenkins;
32 import net.sf.json.JSONObject;
33 import org.kohsuke.stapler.Stapler;
34
35 import java.util.AbstractList;
36 import java.util.Iterator;
37 import java.util.List;
38 import java.util.concurrent.CopyOnWriteArrayList;
39
40 /**
41 * List of {@link Descriptor}s.
42 *
43 * <p>
44 * Before Hudson 1.286, this class stored {@link Descriptor}s directly, but since 1.286,
45 * this class works in two modes that are rather different.
46 *
47 * <p>
48 * One is the compatibility mode, where it works just like pre 1.286 and store everything locally,
49 * disconnected from any of the additions of 1.286. This is necessary for situations where
50 * {@link DescriptorList} is owned by pre-1.286 plugins where this class doesn't know 'T'.
51 * In this mode, {@link #legacy} is non-null but {@link #type} is null.
52 *
53 * <p>
54 * The other mode is the new mode, where the {@link Descriptor}s are actually stored in {@link ExtensionList}
55 * (see {@link jenkins.model.Jenkins#getDescriptorList(Class)}) and this class acts as a view to it. This enables
56 * bi-directional interoperability &mdash; both descriptors registred automatically and descriptors registered
57 * manually are visible from both {@link DescriptorList} and {@link ExtensionList}. In this mode,
58 * {@link #legacy} is null but {@link #type} is non-null.
59 *
60 * <p>
61 * The number of plugins that define extension points are limited, so we expect to be able to remove
62 * this dual behavior first, then when everyone stops using {@link DescriptorList}, we can remove this class
63 * altogether.
64 *
65 * @author Kohsuke Kawaguchi
66 * @since 1.161
67 */
68 public final class DescriptorList<T extends Describable<T>> extends AbstractList<Descriptor<T>> {
69
70 private final Class<T> type;
71
72 private final CopyOnWriteArrayList<Descriptor<T>> legacy;
73
74 /**
75 * This will create a legacy {@link DescriptorList} that is disconnected from
76 * {@link ExtensionList}.
77 *
78 * @deprecated
79 * As of 1.286. Use {@link #DescriptorList(Class)} instead.
80 */
81 public DescriptorList(Descriptor<T>... descriptors) {
82 this.type = null;
83 this.legacy = new CopyOnWriteArrayList<Descriptor<T>>(descriptors);
84 }
85
86 /**
87 * Creates a {@link DescriptorList} backed by {@link ExtensionList}.
88 */
89 public DescriptorList(Class<T> type) {
90 this.type = type;
91 this.legacy = null;
92 }
93
94 @Override
95 public Descriptor<T> get(int index) {
96 return store().get(index);
97 }
98
99 @Override
100 public int size() {
101 return store().size();
102 }
103
104 @Override
105 public Iterator<Descriptor<T>> iterator() {
106 return store().iterator();
107 }
108
109 /**
110 * {@inheritDoc}
111 *
112 * @deprecated
113 * As of 1.286. Put {@link Extension} on your descriptor to have it auto-registered,
114 * instead of registering a descriptor manually.
115 */
116 @Override
117 public boolean add(Descriptor<T> d) {
118 return store().add(d);
119 }
120
121 /**
122 * {@inheritDoc}
123 *
124 * @deprecated
125 * As of 1.286. Put {@link Extension} on your descriptor to have it auto-registered,
126 * instead of registering a descriptor manually.
127 */
128 @Override
129 public void add(int index, Descriptor<T> element) {
130 add(element); // order is ignored
131 }
132
133 @Override
134 public boolean remove(Object o) {
135 return store().remove(o);
136 }
137
138 /**
139 * Gets the actual data store. This is the key to control the dual-mode nature of {@link DescriptorList}
140 */
141 private List<Descriptor<T>> store() {
142 if(type==null)
143 return legacy;
144 else
145 return Jenkins.getInstance().<T,Descriptor<T>>getDescriptorList(type);
146 }
147
148 /**
149 * Creates a new instance of a {@link Describable}
150 * from the structured form submission data posted
151 * by a radio button group.
152 */
153 public T newInstanceFromRadioList(JSONObject config) throws FormException {
154 if(config.isNullObject())
155 return null; // none was selected
156 int idx = config.getInt("value");
157 return get(idx).newInstance(Stapler.getCurrentRequest(),config);
158 }
159
160 public T newInstanceFromRadioList(JSONObject parent, String name) throws FormException {
161 return newInstanceFromRadioList(parent.getJSONObject(name));
162 }
163
164 /**
165 * Finds a descriptor by their {@link Descriptor#getId()}.
166 *
167 * If none is found, null is returned.
168 */
169 public Descriptor<T> findByName(String id) {
170 for (Descriptor<T> d : this)
171 if(d.getId().equals(id))
172 return d;
173 return null;
174 }
175
176 /**
177 * No-op method used to force the class initialization of the given class.
178 * The class initialization in turn is expected to put the descriptor
179 * into the {@link DescriptorList}.
180 *
181 * <p>
182 * This is necessary to resolve the class initialization order problem.
183 * Often a {@link DescriptorList} is defined in the base class, and
184 * when it tries to initialize itself by listing up descriptors of known
185 * sub-classes, they might not be available in time.
186 *
187 * @since 1.162
188 */
189 public void load(Class<? extends Describable> c) {
190 try {
191 Class.forName(c.getName(), true, c.getClassLoader());
192 } catch (ClassNotFoundException e) {
193 throw new AssertionError(e); // Can't happen
194 }
195 }
196
197 /**
198 * Finds the descriptor that has the matching fully-qualified class name.
199 */
200 public Descriptor<T> find(String fqcn) {
201 return Descriptor.find(this,fqcn);
202 }
203 }
204