Package hudson.model

Class TopLevelItemDescriptor

java.lang.Object
hudson.model.Descriptor<TopLevelItem>
hudson.model.TopLevelItemDescriptor
All Implemented Interfaces:
Saveable, Loadable, OnMaster, IconSpec
Direct Known Subclasses:
AbstractProject.AbstractProjectDescriptor
public abstract class TopLevelItemDescriptor extends Descriptor<TopLevelItem> implements IconSpec
Descriptor for TopLevelItems.
Author:
Kohsuke Kawaguchi

  • Constructor Details

    • TopLevelItemDescriptor

      protected TopLevelItemDescriptor(Class<? extends TopLevelItem> clazz)

    • TopLevelItemDescriptor

      protected TopLevelItemDescriptor()
      Infers the type of the corresponding TopLevelItem 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 Details

    • isApplicable

      public boolean isApplicable(Descriptor descriptor)
      TopLevelItemDescriptors often uses other descriptors to decorate itself. This method allows the subtype of TopLevelItemDescriptors to filter them out.

      This is useful for a workflow/company specific item type that wants to eliminate options that the user would see.

      Since:
      1.294

    • isApplicableIn

      public boolean isApplicableIn(ItemGroup parent)
      TopLevelItemDescriptors often may want to limit the scope within which they can be created. This method allows the subtype of TopLevelItemDescriptors to filter them out.
      Since:
      1.607

    • checkApplicableIn

      public final void checkApplicableIn(ItemGroup parent)
      Checks if this top level item is applicable within the specified item group.

      This is just a convenience function.

      Since:
      1.607

    • testInstance

      public boolean testInstance(TopLevelItem i)
      Tests if the given instance belongs to this descriptor, in the sense that this descriptor can produce items like the given one.

      TopLevelItemDescriptors that act like a wizard and produces different object types than Descriptor.clazz can override this method to augment instance-descriptor relationship.

      Since:
      1.410

    • 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 Descriptor.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.

      Used as the caption when the user chooses what item type to create. The descriptor implementation also needs to have newInstanceDetail.jelly script, which will be used to render the text below the caption that explains the item type.

      Overrides:
      getDisplayName in class Descriptor<TopLevelItem>

    • getDescription

      @NonNull public String getDescription()
      A description of this kind of item type. This description can contain HTML code but it is recommended that you use plain text in order to be consistent with the rest of Jenkins. This method should be called from a thread where Stapler is handling an HTTP request, otherwise it will return an empty string.
      Returns:
      A string, by default the value from newInstanceDetail view is taken.
      Since:
      2.0

    • getCategoryId

      @NonNull public String getCategoryId()
      Used to categorize this kind of item type. @see ItemCategory
      Returns:
      A string with the category identifier, ItemCategory.UncategorizedCategory.getId() by default.
      Since:
      2.0

    • getIconFilePathPattern

      @CheckForNull @Deprecated public String getIconFilePathPattern()
      Deprecated.
      prefer getIconClassName()
      Represents a file path pattern to get the Item icon in different sizes. For example: plugin/plugin-shortname/images/:size/item.png, where :size represents the different icon sizes used commonly in Jenkins project: 16x16, 24x24, 32x32 or 48x48
      Returns:
      A string or null if it is not defined.
      Since:
      2.0
      See Also:

    • getIconFilePath

      @CheckForNull @Deprecated public String getIconFilePath(String size)
      Deprecated.
      prefer getIconClassName()
      An icon file path associated to a specific size.
      Parameters:
      size - A string with values that represent the common sizes: 16x16, 24x24, 32x32 or 48x48
      Returns:
      A string or null if it is not defined.
      Since:
      2.0

    • getIconClassName

      public String getIconClassName()
      Get the Item's Icon class specification e.g. 'icon-notepad'.

      Note: do NOT include icon size specifications (such as 'icon-sm').

      Specified by:
      getIconClassName in interface IconSpec
      Returns:
      The Icon class specification e.g. 'icon-notepad'.

    • newInstance

      @Deprecated public TopLevelItem newInstance(org.kohsuke.stapler.StaplerRequest req) throws Descriptor.FormException
      Deprecated.
      since 2007-01-19. This is not a valid operation for Items.
      Overrides:
      newInstance in class Descriptor<TopLevelItem>
      Throws:
      Descriptor.FormException

    • newInstance

      @Deprecated public TopLevelItem newInstance(String name)
      Deprecated.
      as of 1.390 Use newInstance(ItemGroup, String)
      Creates a new TopLevelItem.

    • newInstance

      public abstract TopLevelItem newInstance(ItemGroup parent, String name)
      Creates a new TopLevelItem for the specified parent.
      Since:
      1.390

    • all

      public static ExtensionList<TopLevelItemDescriptor> all()
      Returns all the registered TopLevelItem descriptors.