File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\util\ListBoxModel.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.model.ModelObject;
27 import org.kohsuke.stapler.HttpResponse;
28 import org.kohsuke.stapler.StaplerRequest;
29 import org.kohsuke.stapler.StaplerResponse;
30 import org.kohsuke.stapler.export.Exported;
31 import org.kohsuke.stapler.export.ExportedBean;
32 import org.kohsuke.stapler.export.Flavor;
33
34 import javax.servlet.ServletException;
35 import java.io.IOException;
36 import java.util.ArrayList;
37 import java.util.Arrays;
38 import java.util.Collection;
39
40 /**
41 * Model object of dynamically filled list box.
42 *
43 * <h2>Usage</h2>
44 * <p>
45 * The dynamic list box support allows the SELECT element to change its options dynamically
46 * by using the values given by the server.
47 *
48 * <p>
49 * To use this, HTML needs to declare the SELECT element:
50 *
51 * <pre><xmp>
52 * <select id='foo'>
53 * <option>Fetching values...</optoin>
54 * </select>
55 * </xmp></pre>
56 *
57 * <p>
58 * The SELECT element may have initial option values (in fact in most cases having initial
59 * values are desirable to avoid the client from submitting the form before the AJAX call
60 * updates the SELECT element.) It should also have an ID (although if you can get
61 * to the DOM element by other means, that's fine, too.)
62 *
63 * <p>
64 * Other parts of the HTML can initiate the SELECT element update by using the "updateListBox"
65 * function, defined in <tt>hudson-behavior.js</tt>. The following example does it
66 * when the value of the textbox changes:
67 *
68 * <pre><xmp>
69 * <input type="textbox" onchange="updateListBox('list','optionValues?value='+encode(this.value))"/>
70 * </xmp></pre>
71 *
72 * <p>
73 * The first argument is the SELECT element or the ID of it (see Prototype.js <tt>$(...)</tt> function.)
74 * The second argument is the URL that returns the options list.
75 *
76 * <p>
77 * The URL usually maps to the <tt>doXXX</tt> method on the server, which uses {@link ListBoxModel}
78 * for producing option values. See the following example:
79 *
80 * <pre>
81 * public ListBoxModel doOptionValues(@QueryParameter("value") String value) throws IOException, ServletException {
82 * ListBoxModel m = new ListBoxModel();
83 * for(int i=0; i<5; i++)
84 * m.add(value+i,value+i);
85 * // make the third option selected initially
86 * m.get(3).selected = true;
87 * return m;
88 * }
89 * </pre>
90 * @since 1.123
91 * @author Kohsuke Kawaguchi
92 */
93 @ExportedBean
94 public class ListBoxModel extends ArrayList<ListBoxModel.Option> implements HttpResponse {
95
96 @ExportedBean(defaultVisibility=999)
97 public static final class Option {
98 /**
99 * Text to be displayed to user.
100 */
101 @Exported
102 public String name;
103 /**
104 * The value that gets sent to the server when the form is submitted.
105 */
106 @Exported
107 public String value;
108
109 /**
110 * True to make this item selected.
111 */
112 @Exported
113 public boolean selected;
114
115 public Option(String name, String value) {
116 this(name,value,false);
117 }
118
119 public Option(String name) {
120 this(name,name,false);
121 }
122
123 public Option(String name, String value, boolean selected) {
124 this.name = name;
125 this.value = value;
126 this.selected = selected;
127 }
128 }
129
130 public ListBoxModel(int initialCapacity) {
131 super(initialCapacity);
132 }
133
134 public ListBoxModel() {
135 }
136
137 public ListBoxModel(Collection<Option> c) {
138 super(c);
139 }
140
141 public ListBoxModel(Option... data) {
142 super(Arrays.asList(data));
143 }
144
145 public void add(String displayName, String value) {
146 add(new Option(displayName,value));
147 }
148
149 public void add(ModelObject usedForDisplayName, String value) {
150 add(usedForDisplayName.getDisplayName(), value);
151 }
152
153 /**
154 * A version of the {@link #add(String, String)} method where the display name and the value are the same.
155 */
156 public ListBoxModel add(String nameAndValue) {
157 add(nameAndValue,nameAndValue);
158 return this;
159 }
160
161 public void writeTo(StaplerRequest req,StaplerResponse rsp) throws IOException, ServletException {
162 rsp.serveExposedBean(req,this,Flavor.JSON);
163 }
164
165 public void generateResponse(StaplerRequest req, StaplerResponse rsp, Object node) throws IOException, ServletException {
166 writeTo(req,rsp);
167 }
168
169 /**
170 * @deprecated
171 * Exposed for stapler. Not meant for programatic consumption.
172 */
173 @Exported
174 public Option[] values() {
175 return toArray(new Option[size()]);
176 }
177 }
178