/hudson-core/src/main/java/hudson/Extension.java

 1/*
 2 * The MIT License
 3 *
 4 * Copyright (c) 2004-2010, Sun Microsystems, 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 */
24package hudson;
25
26import net.java.sezpoz.Indexable;
27
28import java.lang.annotation.Documented;
29import java.lang.annotation.Retention;
30import java.lang.annotation.Target;
31
32import static java.lang.annotation.ElementType.*;
33import static java.lang.annotation.RetentionPolicy.RUNTIME;
34
35/**
36 * Marks a field, a method, or a class for automatic discovery, so that Hudson can locate
37 * implementations of {@link ExtensionPoint}s automatically.
38 *
39 * <p>
40 * (In contrast, in earlier Hudson, the registration was manual.)
41 *
42 * <p>
43 * In a simplest case, put this on your class, and Hudson will create an instance of it
44 * and register it to the appropriate {@link ExtensionList}.
45 *
46 * <p>
47 * If you'd like Hudson to call
48 * a factory method instead of a constructor, put this annotation on your static factory
49 * method. Hudson will invoke it and if the method returns a non-null instance, it'll be
50 * registered. The return type of the method is used to determine which {@link ExtensionList}
51 * will get the instance.
52 *
53 * Finally, you can put this annotation on a static field if the field contains a reference
54 * to an instance that you'd like to register.
55 *
56 * <p>
57 * This is the default way of having your implementations auto-registered to Hudson,
58 * but Hudson also supports arbitrary DI containers for hosting your implementations.
59 * See {@link ExtensionFinder} for more details.
60 *
61 * @author Kohsuke Kawaguchi
62 * @since 1.286
63 * @see <a href="http://java.net/projects/sezpoz/">SezPoz</a>
64 * @see ExtensionFinder
65 * @see ExtensionList
66 */
67@Indexable
68@Retention(RUNTIME)
69@Target({TYPE, FIELD, METHOD})
70@Documented
71public @interface Extension {
72    /**
73     * Used for sorting extensions.
74     *
75     * Extensions will be sorted in the descending order of the ordinal.
76     * This is a rather poor approach to the problem, so its use is generally discouraged.
77     *
78     * @since 1.306
79     */
80    double ordinal() default 0;
81
82    /**
83     * If an extension is optional, don't log any class loading errors when reading it.
84     * @since 1.358
85     */
86    boolean optional() default false;
87}