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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2011, CloudBees, Inc.
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.ExtensionPoint;
29 import hudson.model.AbstractProject;
30 import jenkins.model.Jenkins;
31
32 /**
33 * Provides the alternative text to be rendered in the UI.
34 *
35 * <p>
36 * In a few limited places in Jenkins, we want to provide an ability for plugins to replace
37 * the text to be shown in the UI. Since each such case is rather trivial and can't justify
38 * its own extension point, we consolidate all such use cases into a single extension point.
39 *
40 * <p>
41 * Each such overridable UI text can have a context, which represents some information
42 * that enables the {@link AlternativeUiTextProvider} to make intelligent decision. This
43 * is normally some kind of a model object, such as {@link AbstractProject}.
44 *
45 * <p>
46 * To define a new UI text that can be overridable by {@link AlternativeUiTextProvider},
47 * define a constant of {@link Message} (parameterized with the context object type),
48 * then call {@link #get(Message, Object)} to obtain a text.
49 *
50 * <p>
51 * To define an implementation that overrides text, define a subtype and put @{@link Extension} on it.
52 * See {@link AbstractProject#getBuildNowText()} as an example.
53 *
54 * @author Kohsuke Kawaguchi
55 * @since 1.401
56 */
57 public abstract class AlternativeUiTextProvider implements ExtensionPoint {
58 /**
59 * Provides an opportunity to override the message text.
60 *
61 * @param text
62 * Always non-null. Caller should pass in a {@link Message} constant that
63 * represents the text that we are being considered.
64 * @param context
65 * Context object. See class javadoc above.
66 */
67 public abstract <T> String getText(Message<T> text, T context);
68
69 /**
70 * All the registered extension point instances.
71 */
72 public static ExtensionList<AlternativeUiTextProvider> all() {
73 return Jenkins.getInstance().getExtensionList(AlternativeUiTextProvider.class);
74 }
75
76 public static <T> String get(Message<T> text, T context, String defaultValue) {
77 String s = get(text,context);
78 return s!=null ? s : defaultValue;
79 }
80
81 /**
82 * Consults all the existing {@link AlternativeUiTextProvider} and return an override, if any,
83 * or null.
84 */
85 public static <T> String get(Message<T> text, T context) {
86 for (AlternativeUiTextProvider p : all()) {
87 String s = p.getText(text, context);
88 if (s!=null)
89 return s;
90 }
91 return null;
92 }
93
94 /**
95 * Each instance of this class represents a text that can be replaced by {@link AlternativeUiTextProvider}.
96 *
97 * @param <T>
98 * Context object type. Use {@link Void} to indicate that there's no context.
99 */
100 public static final class Message<T> {
101 // decided not to retain T as Class so that we can have Message<List<Foo>>, for example.
102
103 /**
104 * Assists pattern matching in the {@link AlternativeUiTextProvider} implementation.
105 */
106 @SuppressWarnings({"unchecked"})
107 public T cast(Object context) {
108 return (T)context;
109 }
110 }
111 }
112