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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2011, Sun Microsystems, Inc., Kohsuke Kawaguchi, Yahoo! Inc.,
5 * Manufacture Francaise des Pneumatiques Michelin, Romain Seguy
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23 * THE SOFTWARE.
24 */
25 package hudson.model;
26
27 import hudson.Functions;
28 import hudson.security.PermissionScope;
29 import org.kohsuke.stapler.StaplerRequest;
30
31 import java.io.IOException;
32 import java.util.Collection;
33
34 import hudson.search.SearchableModelObject;
35 import hudson.security.Permission;
36 import hudson.security.PermissionGroup;
37 import hudson.security.AccessControlled;
38
39 /**
40 * Basic configuration unit in Hudson.
41 *
42 * <p>
43 * Every {@link Item} is hosted in an {@link ItemGroup} called "parent",
44 * and some {@link Item}s are {@link ItemGroup}s. This form a tree
45 * structure, which is rooted at {@link jenkins.model.Jenkins}.
46 *
47 * <p>
48 * Unlike file systems, where a file can be moved from one directory
49 * to another, {@link Item} inherently belongs to a single {@link ItemGroup}
50 * and that relationship will not change.
51 * Think of
52 * <a href="http://images.google.com/images?q=Windows%20device%20manager">Windows device manager</a>
53 * &mdash; an HDD always show up under 'Disk drives' and it can never be moved to another parent.
54 *
55 * Similarly, {@link ItemGroup} is not a generic container. Each subclass
56 * of {@link ItemGroup} can usually only host a certain limited kinds of
57 * {@link Item}s.
58 *
59 * <p>
60 * {@link Item}s have unique {@link #getName() name}s that distinguish themselves
61 * among their siblings uniquely. The names can be combined by '/' to form an
62 * item full name, which uniquely identifies an {@link Item} inside the whole {@link jenkins.model.Jenkins}.
63 *
64 * @author Kohsuke Kawaguchi
65 * @see Items
66 * @see ItemVisitor
67 */
68 public interface Item extends PersistenceRoot, SearchableModelObject, AccessControlled {
69 /**
70 * Gets the parent that contains this item.
71 */
72 ItemGroup<? extends Item> getParent();
73
74 /**
75 * Gets all the jobs that this {@link Item} contains as descendants.
76 */
77 Collection<? extends Job> getAllJobs();
78
79 /**
80 * Gets the name of the item.
81 *
82 * <p>
83 * The name must be unique among other {@link Item}s that belong
84 * to the same parent.
85 *
86 * <p>
87 * This name is also used for directory name, so it cannot contain
88 * any character that's not allowed on the file system.
89 *
90 * @see #getFullName()
91 */
92 String getName();
93
94 /**
95 * Gets the full name of this item, like "abc/def/ghi".
96 *
97 * <p>
98 * Full name consists of {@link #getName() name}s of {@link Item}s
99 * that lead from the root {@link jenkins.model.Jenkins} to this {@link Item},
100 * separated by '/'. This is the unique name that identifies this
101 * {@link Item} inside the whole {@link jenkins.model.Jenkins}.
102 *
103 * @see jenkins.model.Jenkins#getItemByFullName(String,Class)
104 */
105 String getFullName();
106
107 /**
108 * Gets the human readable short name of this item.
109 *
110 * <p>
111 * This method should try to return a short concise human
112 * readable string that describes this item.
113 * The string need not be unique.
114 *
115 * <p>
116 * The returned string should not include the display names
117 * of {@link #getParent() ancestor items}.
118 */
119 String getDisplayName();
120
121 /**
122 * Works like {@link #getDisplayName()} but return
123 * the full path that includes all the display names
124 * of the ancestors.
125 */
126 String getFullDisplayName();
127
128 /**
129 * Gets the relative name to this item from the specified group.
130 *
131 * @since 1.419
132 * @return
133 * String like "../foo/bar"
134 */
135 String getRelativeNameFrom(ItemGroup g);
136
137 /**
138 * Short for {@code getRelativeNameFrom(item.getParent())}
139 *
140 * @since 1.419
141 */
142 String getRelativeNameFrom(Item item);
143
144 /**
145 * Returns the URL of this item relative to the context root of the application.
146 *
147 * @see AbstractItem#getUrl() for how to implement this.
148 *
149 * @return
150 * URL that ends with '/'.
151 */
152 String getUrl();
153
154 /**
155 * Returns the URL of this item relative to the parent {@link ItemGroup}.
156 * @see AbstractItem#getShortUrl() for how to implement this.
157 *
158 * @return
159 * URL that ends with '/'.
160 */
161 String getShortUrl();
162
163 /**
164 * Returns the absolute URL of this item. This relies on the current
165 * {@link StaplerRequest} to figure out what the host name is,
166 * so can be used only during processing client requests.
167 *
168 * @return
169 * absolute URL.
170 * @throws IllegalStateException
171 * if the method is invoked outside the HTTP request processing.
172 *
173 * @deprecated
174 * This method shall <b>NEVER</b> be used during HTML page rendering, as it won't work with
175 * network set up like Apache reverse proxy.
176 * This method is only intended for the remote API clients who cannot resolve relative references
177 * (even this won't work for the same reason, which should be fixed.)
178 */
179 String getAbsoluteUrl();
180
181 /**
182 * Called right after when a {@link Item} is loaded from disk.
183 * This is an opporunity to do a post load processing.
184 *
185 * @param name
186 * Name of the directory (not a path --- just the name portion) from
187 * which the configuration was loaded. This usually becomes the
188 * {@link #getName() name} of this item.
189 */
190 void onLoad(ItemGroup<? extends Item> parent, String name) throws IOException;
191
192 /**
193 * When a {@link Item} is copied from existing one,
194 * the files are first copied on the file system,
195 * then it will be loaded, then this method will be invoked
196 * to perform any implementation-specific work.
197 */
198 void onCopiedFrom(Item src);
199
200 /**
201 * When an item is created from scratch (instead of copied),
202 * this method will be invoked. Used as the post-construction initialization.
203 *
204 * @since 1.374
205 */
206 void onCreatedFromScratch();
207
208 /**
209 * Save the settings to a file.
210 *
211 * Use {@link Items#getConfigFile(Item)}
212 * or {@link AbstractItem#getConfigFile()} to obtain the file
213 * to save the data.
214 */
215 void save() throws IOException;
216
217 /**
218 * Deletes this item.
219 */
220 void delete() throws IOException, InterruptedException;
221
222 PermissionGroup PERMISSIONS = new PermissionGroup(Item.class,Messages._Item_Permissions_Title());
223 Permission CREATE = new Permission(PERMISSIONS, "Create", null, Permission.CREATE, PermissionScope.ITEM_GROUP);
224 Permission DELETE = new Permission(PERMISSIONS, "Delete", null, Permission.DELETE, PermissionScope.ITEM);
225 Permission CONFIGURE = new Permission(PERMISSIONS, "Configure", null, Permission.CONFIGURE, PermissionScope.ITEM);
226 Permission READ = new Permission(PERMISSIONS, "Read", null, Permission.READ, PermissionScope.ITEM);
227 Permission DISCOVER = new Permission(PERMISSIONS, "Discover", Messages._AbstractProject_DiscoverPermission_Description(), Permission.READ, PermissionScope.ITEM);
228 Permission EXTENDED_READ = new Permission(PERMISSIONS,"ExtendedRead", Messages._AbstractProject_ExtendedReadPermission_Description(), CONFIGURE, Boolean.getBoolean("hudson.security.ExtendedReadPermission"), new PermissionScope[]{PermissionScope.ITEM});
229 Permission BUILD = new Permission(PERMISSIONS, "Build", Messages._AbstractProject_BuildPermission_Description(), Permission.UPDATE, PermissionScope.ITEM);
230 Permission WORKSPACE = new Permission(PERMISSIONS, "Workspace", Messages._AbstractProject_WorkspacePermission_Description(), Permission.READ, PermissionScope.ITEM);
231 Permission WIPEOUT = new Permission(PERMISSIONS, "WipeOut", Messages._AbstractProject_WipeOutPermission_Description(), null, Functions.isWipeOutPermissionEnabled(), new PermissionScope[]{PermissionScope.ITEM});
232 Permission CANCEL = new Permission(PERMISSIONS, "Cancel", Messages._AbstractProject_CancelPermission_Description(), BUILD, PermissionScope.ITEM);
233 }
234