Package hudson.model

Class Descriptor<T extends Describable<T>>

    • Field Detail

      • clazz

        public final transient Class<? extends T extends Describable<T>> clazz
        The class being described by this descriptor.

    • Constructor Detail

      • Descriptor

        protected Descriptor​(Class<? extends T> clazz)
        Parameters:
        clazz - Pass in self() to have the descriptor describe itself, (this hack is needed since derived types can't call "getClass()" to refer to itself.

      • Descriptor

        protected Descriptor()
        Infers the type of the corresponding Describable from the outer class. This version works when you follow the common convention, where a descriptor is written as the static nested class of the describable class.
        Since:
        1.278

    • Method Detail

      • getDisplayName

        @NonNull
public String getDisplayName()
        Human readable name of this kind of configurable object. Should be overridden for most descriptors, if the display name is visible somehow. As a fallback it uses Class.getSimpleName() on clazz, so for example MyThing from some.pkg.MyThing.DescriptorImpl. Historically some implementations returned null as a way of hiding the descriptor from the UI, but this is generally managed by an explicit method such as isEnabled or isApplicable.

      • getId

        public String getId()
        Uniquely identifies this Descriptor among all the other Descriptors.

        Historically clazz is assumed to be unique, so this method uses that as the default, but if you are adding Descriptors programmatically for the same type, you can change this to disambiguate them.

        To look up Descriptor from ID, use Jenkins.getDescriptor(String).

        Returns:
        Stick to valid Java identifier character, plus '.', which had to be allowed for historical reasons.
        Since:
        1.391

      • getT

        public Class<T> getT()
        Unlike clazz, return the parameter type 'T', which determines the DescriptorExtensionList that this goes to.

        In those situations where subtypes cannot provide the type parameter, this method can be overridden to provide it.

      • getDescriptorFullUrl

        public final String getDescriptorFullUrl()
        Gets the URL that this Descriptor is bound to, relative to the context path.
        Since:
        1.406

      • getCurrentDescriptorByNameUrl

        public static String getCurrentDescriptorByNameUrl()
        Since:
        1.402

      • getCheckMethod

        public FormValidation.CheckMethod getCheckMethod​(String fieldName)
        If the field "xyz" of a Describable has the corresponding "doCheckXyz" method, return the model of the check method.

        This method is used to hook up the form validation method to the corresponding HTML input element.

      • calcFillSettings

        public void calcFillSettings​(String field,
                             Map<String,​Object> attributes)
        Computes the list of other form fields that the given field depends on, via the doFillXyzItems method, and sets that as the 'fillDependsOn' attribute. Also computes the URL of the doFillXyzItems and sets that as the 'fillUrl' attribute.

      • calcAutoCompleteSettings

        public void calcAutoCompleteSettings​(String field,
                                     Map<String,​Object> attributes)
        Computes the auto-completion setting

      • getPropertyType

        @CheckForNull
public Descriptor.PropertyType getPropertyType​(@NonNull
                                               Object instance,
                                               @NonNull
                                               String field)
        Used by Jelly to abstract away the handling of global.jelly vs config.jelly databinding difference.

      • getGlobalPropertyType

        public Descriptor.PropertyType getGlobalPropertyType​(String field)
        Obtains the property type of the given field of this descriptor.

      • getJsonSafeClassName

        public final String getJsonSafeClassName()
        Gets the class name nicely escaped to be usable as a key in the structured form submission.

      • newInstance

        public T newInstance​(@Nullable
                     org.kohsuke.stapler.StaplerRequest req,
                     @NonNull
                     net.sf.json.JSONObject formData)
              throws Descriptor.FormException
        Creates a configured instance from the submitted form.

        Hudson only invokes this method when the user wants an instance of T. So there's no need to check that in the implementation.

        The default implementation of this method uses bindJSON(org.kohsuke.stapler.StaplerRequest, java.lang.Class<T>, net.sf.json.JSONObject) which performs the databinding on the constructor of clazz.

        For some types of Describable, such as ListViewColumn, this method can be invoked with null request object for historical reason. Such design is considered broken, but due to the compatibility reasons we cannot fix it. Because of this, the default implementation gracefully handles null request, but the contract of the method still is "request is always non-null." Extension points that need to define the "default instance" semantics should define a descriptor subtype and add the no-arg newInstance method.

        Parameters:
        req - Always non-null (see note above.) This object includes represents the entire submission.
        formData - The JSON object that captures the configuration data for this Descriptor. See the developer documentation. Always non-null.
        Throws:
        Descriptor.FormException - Signals a problem in the submitted form.
        Since:
        1.145

      • getKlass

        public org.kohsuke.stapler.lang.Klass<?> getKlass()
        Returns the Klass object used for the purpose of loading resources from this descriptor. This hook enables other JVM languages to provide more integrated lookup.

      • getHelpFile

        public String getHelpFile()
        Returns the resource path to the help screen HTML, if any.

        Starting 1.282, this method uses "convention over configuration" — you should just put the "help.html" (and its localized versions, if any) in the same directory you put your Jelly view files, and this method will automatically does the right thing.

        This value is relative to the context root of Hudson, so normally the values are something like "/plugin/emma/help.html" to refer to static resource files in a plugin, or "/publisher/EmmaPublisher/abc" to refer to Jelly script abc.jelly or a method EmmaPublisher.doAbc().

        Returns:
        null to indicate that there's no help.

      • getHelpFile

        public String getHelpFile​(String fieldName)
        Returns the path to the help screen HTML for the given field.

        The help files are assumed to be at "help/FIELDNAME.html" with possible locale variations.

      • getHelpFile

        public String getHelpFile​(org.kohsuke.stapler.lang.Klass<?> clazz,
                          String fieldName)

      • addHelpFileRedirect

        protected void addHelpFileRedirect​(String fieldName,
                                   Class<? extends Describable> owner,
                                   String fieldNameToRedirectTo)
        Tells Jenkins that the help file for the field 'fieldName' is defined in the help file for the 'fieldNameToRedirectTo' in the 'owner' class.
        Since:
        1.425

      • isInstance

        public final boolean isInstance​(T instance)
        Checks if the given object is created from this Descriptor.

      • isSubTypeOf

        public final boolean isSubTypeOf​(Class type)
        Checks if the type represented by this descriptor is a subtype of the given type.

      • configure

        public boolean configure​(org.kohsuke.stapler.StaplerRequest req,
                         net.sf.json.JSONObject json)
                  throws Descriptor.FormException
        Invoked when the global configuration page is submitted. Can be overridden to store descriptor-specific information.
        Parameters:
        json - The JSON object that captures the configuration data for this Descriptor. See the developer documentation.
        Returns:
        false to keep the client in the same config page.
        Throws:
        Descriptor.FormException

      • getConfigPage

        public String getConfigPage()

      • getGlobalConfigPage

        public String getGlobalConfigPage()

      • getCategory

        @NonNull
public GlobalConfigurationCategory getCategory()
        Define the global configuration category the global config of this Descriptor is in.
        Returns:
        never null, always the same value for a given instance of Descriptor.
        Since:
        2.0, used to be in GlobalConfiguration before that.

      • getRequiredGlobalConfigPagePermission

        @NonNull
public Permission getRequiredGlobalConfigPagePermission()
        Returns the permission type needed in order to access the getGlobalConfigPage() for this descriptor. By default, requires Jenkins.ADMINISTER permission. For now this only applies to descriptors configured through the global (GlobalConfigurationCategory.Unclassified) configuration. Override to return something different if appropriate. The only currently supported alternative return value is Jenkins.MANAGE.
        Returns:
        Permission required to globally configure this descriptor.
        Since:
        2.222

      • getViewPage

        protected final String getViewPage​(Class<?> clazz,
                                   String pageName)

      • getPossibleViewNames

        protected List<String> getPossibleViewNames​(String baseName)

      • save

        public void save()
        Saves the configuration info to the disk.
        Specified by:
        save in interface Saveable

      • load

        public void load()
        Loads the data from the disk into this object.

        The constructor of the derived class must call this method. (If we do that in the base class, the derived class won't get a chance to set default values.)

        Specified by:
        load in interface Loadable

      • getConfigFile

        protected XmlFile getConfigFile()

      • getPlugin

        protected PluginWrapper getPlugin()
        Returns the plugin in which this descriptor is defined.
        Returns:
        null to indicate that this descriptor came from the core.

      • doHelp

        public void doHelp​(org.kohsuke.stapler.StaplerRequest req,
                   org.kohsuke.stapler.StaplerResponse rsp)
            throws IOException,
                   javax.servlet.ServletException
        Serves help.html from the resource of clazz.
        Throws:
        IOException
        javax.servlet.ServletException

      • getStaticHelpUrl

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static URL getStaticHelpUrl​(org.kohsuke.stapler.StaplerRequest req,
                                   org.kohsuke.stapler.lang.Klass<?> c,
                                   String suffix)

      • toArray

        public static <T> T[] toArray​(T... values)

      • toList

        public static <T> List<T> toList​(T... values)

      • newInstancesFromHeteroList

        public static <T extends Describable<T>> List<T> newInstancesFromHeteroList​(org.kohsuke.stapler.StaplerRequest req,
                                                                            net.sf.json.JSONObject formData,
                                                                            String key,
                                                                            Collection<? extends Descriptor<T>> descriptors)
                                                                     throws Descriptor.FormException
        Used to build Describable instance list from <f:hetero-list> tag.
        Parameters:
        req - Request that represents the form submission.
        formData - Structured form data that represents the contains data for the list of describables.
        key - The JSON property name for 'formData' that represents the data for the list of describables.
        descriptors - List of descriptors to create instances from.
        Returns:
        Can be empty but never null.
        Throws:
        Descriptor.FormException

      • findById

        @CheckForNull
public static <T extends Descriptor> T findById​(Collection<? extends T> list,
                                                String id)
        Finds a descriptor from a collection by its ID.
        Parameters:
        id - should match getId()
        Since:
        1.610

      • findByDescribableClassName

        @CheckForNull
public static <T extends Descriptor> T findByDescribableClassName​(Collection<? extends T> list,
                                                                  String className)
        Finds a descriptor from a collection by the class name of the Describable it describes.
        Parameters:
        className - should match Class.getName() of a clazz
        Since:
        1.610

      • self

        protected static Class self()