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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi, Michael B. Donohue
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.Functions;
27 import hudson.tasks.test.TestResultProjectAction;
28
29 /**
30 * Object that contributes additional information, behaviors, and UIs to {@link ModelObject}
31 * (more specifically {@link Actionable} objects, which most interesting {@link ModelObject}s are.)
32 *
33 * <p>
34 * {@link Action}s added to a model object creates additional URL subspace under the parent model object,
35 * through which it can interact with users. {@link Action}s are also capable of exposing themselves
36 * to the left hand side menu of a {@link ModelObject} (for example to {@link Project}, {@link Build}, and etc.)
37 *
38 * <p>
39 * Some actions use the latter without the former (for example, to add a link to an external website),
40 * while others do the former without the latter (for example, to just draw some graphs in <tt>floatingBox.jelly</tt>),
41 * and still some others do both.
42 *
43 * <h2>Views</h2>
44 * <p>
45 * If an action has a view named <tt>floatingBox.jelly</tt>,
46 * it will be displayed as a floating box on the top page of
47 * the target {@link ModelObject}. (For example, this is how
48 * the JUnit test result trend shows up in the project top page.
49 * See {@link TestResultProjectAction}.
50 *
51 * <p>
52 * On the target {@link ModelObject} page, actions are rendered as an item in the side panel
53 * by the "/lib/hudson:actions" jelly tag, but you can override this for your action by
54 * writing {@code action.jelly}. See the "actions" tag for what the default handling is and
55 * tweak from there. One of the use cases of this is to show nested actions, like where
56 * Jenkins show the option to wipe out the workspace inside the workspace link:
57 *
58 * <pre>
59 * &lt;l:task icon="images/24x24/folder.gif" href="${url}/ws/" title="${%Workspace}">
60 * &lt;l:task icon="images/24x24/folder-delete.gif" href="${url}/wipeOutWorkspace" title="${%Wipe Out Workspace}" />
61 * &lt;/l:task>
62 * </pre>
63 *
64 * <h2>Persistence</h2>
65 * <p>
66 * Actions are often persisted as a part of {@link Actionable}
67 * (for example with {@link Build}) via XStream. In some other cases,
68 * {@link Action}s are transient and not persisted (such as
69 * when it's used with {@link Job}).
70 *
71 * @author Kohsuke Kawaguchi
72 */
73 public interface Action extends ModelObject {
74 /**
75 * Gets the file name of the icon.
76 *
77 * @return
78 * If just a file name (like "abc.gif") is returned, it will be
79 * interpreted as a file name inside <tt>/images/24x24</tt>.
80 * This is useful for using one of the stock images.
81 * <p>
82 * If an absolute file name that starts from '/' is returned (like
83 * "/plugin/foo/abc.gif'), then it will be interpreted as a path
84 * from the context root of Jenkins. This is useful to pick up
85 * image files from a plugin.
86 * <p>
87 * Finally, return null to hide it from the task list. This is normally not very useful,
88 * but this can be used for actions that only contribute <tt>floatBox.jelly</tt>
89 * and no task list item. The other case where this is useful is
90 * to avoid showing links that require a privilege when the user is anonymous.
91 * @see Functions#isAnonymous()
92 * @see Functions#getIconFilePath(Action)
93 */
94 String getIconFileName();
95
96 /**
97 * Gets the string to be displayed.
98 *
99 * The convention is to capitalize the first letter of each word,
100 * such as "Test Result".
101 */
102 String getDisplayName();
103
104 /**
105 * Gets the URL path name.
106 *
107 * <p>tions
108 * For example, if this method returns "xyz", and if the parent object
109 * (that this action is associated with) is bound to /foo/bar/zot,
110 * then this action object will be exposed to /foo/bar/zot/xyz.
111 *
112 * <p>
113 * This method should return a string that's unique among other {@link Action}s.
114 *
115 * <p>
116 * The returned string can be an absolute URL, like "http://www.sun.com/",
117 * which is useful for directly connecting to external systems.
118 *
119 * <p>
120 * If the returned string starts with '/', like '/foo', then it's assumed to be
121 * relative to the context path of the Jenkins webapp.
122 *
123 * @return
124 * null if this action object doesn't need to be bound to web
125 * (when you do that, be sure to also return null from {@link #getIconFileName()}.
126 * @see Functions#getActionUrl(String, Action)
127 */
128 String getUrlName();
129 }
130