hudson.model

Class Descriptor<T extends Describable<T>>

java.lang.Object

hudson.model.Descriptor<T>

All Implemented Interfaces:

Saveable, OnMaster

Direct Known Subclasses:

AbstractNodeMonitorDescriptor, ArtifactManagerFactoryDescriptor, AuthorizationStrategy.Unsecured.DescriptorImpl, BuildDiscarderDescriptor, BuildStepDescriptor, BuildWrapperDescriptor, CaptchaSupportDescriptor, ComputerConnectorDescriptor, ComputerSet.DescriptorImpl, ConsoleAnnotationDescriptor, Correlator, CrumbIssuerDescriptor, DelegatingComputerLauncher.DescriptorImpl, EnvVarsFilterLocalRuleDescriptor, FingerprintStorageDescriptor, FullControlOnceLoggedInAuthorizationStrategy.DescriptorImpl, GlobalBuildDiscarderStrategyDescriptor, GlobalConfiguration, GlobalSecurityConfiguration.DescriptorImpl, GlobalSettingsProviderDescriptor, HudsonPrivateSecurityRealm.DescriptorImpl, IdStrategyDescriptor, JNLPLauncher.DescriptorImpl, JobPropertyDescriptor, LabelAtomPropertyDescriptor, LegacyAuthorizationStrategy.DescriptorImpl, LegacySecurityRealm.DescriptorImpl, ListViewColumnDescriptor, MarkupFormatterDescriptor, MyViewsTabBarDescriptor, NodeDescriptor, PageDecorator, ParameterDefinition.ParameterDescriptor, ProjectNamingStrategy.ProjectNamingStrategyDescriptor, PropertyDescriptor, ProxyConfiguration.DescriptorImpl, QueueItemAuthenticatorDescriptor, RemotingWorkDirSettings.DescriptorImpl, RetentionStrategy.Always.DescriptorImpl, RetentionStrategy.Demand.DescriptorImpl, SCMCheckoutStrategyDescriptor, SCMDescriptor, SettingsProviderDescriptor, SimplePageDecorator, SimpleScheduledRetentionStrategy.DescriptorImpl, StatusFilter.StatusFilterDescriptor, ToolDescriptor, ToolInstallerDescriptor, TopLevelItemDescriptor, TriggerDescriptor, UserPropertyDescriptor, ViewDescriptor, ViewPropertyDescriptor, ViewsTabBarDescriptor

public abstract class Descriptor<T extends Describable<T>>
extends Object
implements Saveable, OnMaster

Metadata about a configurable instance.

Descriptor is an object that has metadata about a Describable object, and also serves as a factory (in a way this relationship is similar to Object/Class relationship. A Descriptor/Describable combination is used throughout in Hudson to implement a configuration/extensibility mechanism.

Take the list view support as an example, which is implemented in ListView class. Whenever a new view is created, a new ListView instance is created with the configuration information. This instance gets serialized to XML, and this instance will be called to render the view page. This is the job of Describable — each instance represents a specific configuration of a view (what projects are in it, regular expression, etc.)

For Hudson to create such configured ListView instance, Hudson needs another object that captures the metadata of ListView, and that is what a Descriptor is for. ListView class has a singleton descriptor, and this descriptor helps render the configuration form, remember system-wide configuration, and works as a factory.

Descriptor also usually have its associated views.

Persistence

Descriptor can persist data just by storing them in fields. However, it is the responsibility of the derived type to properly invoke save() and load(). load() is automatically invoked as a JSR-250 lifecycle method if derived class do implement PersistentDescriptor.

Reflection Enhancement

Descriptor defines addition to the standard Java reflection and provides reflective information about its corresponding Describable. These are primarily used by tag libraries to keep the Jelly scripts concise.

Author:

Kohsuke Kawaguchi

See Also:

Describable

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Descriptor.FormException
static class	Descriptor.PropertyType Represents a readable property on Describable.
static class	Descriptor.Self Special type indicating that Descriptor describes itself.

Field Summary

Fields

Modifier and Type	Field and Description
Class<? extends T>	clazz The class being described by this descriptor.

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Descriptor() Infers the type of the corresponding Describable from the outer class.
protected	Descriptor(Class<? extends T> clazz)

Method Summary

Modifier and Type	Method and Description
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.
void	calcAutoCompleteSettings(String field, Map<String,Object> attributes) Computes the auto-completion setting
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.
boolean	configure(org.kohsuke.stapler.StaplerRequest req) Deprecated. As of 1.239, use configure(StaplerRequest, JSONObject).
boolean	configure(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject json) Invoked when the global configuration page is submitted.
void	doHelp(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Serves help.html from the resource of clazz.
static <T extends Descriptor> T	find(Collection<? extends T> list, String string) Deprecated. choose between findById(java.util.Collection<? extends T>, java.lang.String) or findByDescribableClassName(java.util.Collection<? extends T>, java.lang.String)
static Descriptor	find(String className) Deprecated. choose between findById(java.util.Collection<? extends T>, java.lang.String) or findByDescribableClassName(java.util.Collection<? extends T>, java.lang.String)
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.
static <T extends Descriptor> T	findById(Collection<? extends T> list, String id) Finds a descriptor from a collection by its ID.
GlobalConfigurationCategory	getCategory() Define the global configuration category the global config of this Descriptor is in.
FormValidation.CheckMethod	getCheckMethod(String fieldName) If the field "xyz" of a Describable has the corresponding "doCheckXyz" method, return the model of the check method.
String	getCheckUrl(String fieldName) Deprecated. since 1.528 Use getCheckMethod(String)
protected XmlFile	getConfigFile()
String	getConfigPage()
static String	getCurrentDescriptorByNameUrl()
String	getDescriptorFullUrl() Gets the URL that this Descriptor is bound to, relative to the context path.
String	getDescriptorUrl() Gets the URL that this Descriptor is bound to, relative to the nearest DescriptorByNameOwner.
String	getDisplayName() Human readable name of this kind of configurable object.
String	getGlobalConfigPage()
Descriptor.PropertyType	getGlobalPropertyType(String field) Obtains the property type of the given field of this descriptor.
String	getHelpFile() Returns the resource path to the help screen HTML, if any.
String	getHelpFile(org.kohsuke.stapler.lang.Klass<?> clazz, String fieldName)
String	getHelpFile(String fieldName) Returns the path to the help screen HTML for the given field.
String	getId() Uniquely identifies this Descriptor among all the other Descriptors.
String	getJsonSafeClassName() Gets the class name nicely escaped to be usable as a key in the structured form submission.
org.kohsuke.stapler.lang.Klass<?>	getKlass() Returns the Klass object used for the purpose of loading resources from this descriptor.
protected PluginWrapper	getPlugin() Returns the plugin in which this descriptor is defined.
protected List<String>	getPossibleViewNames(String baseName)
Descriptor.PropertyType	getPropertyType(Object instance, String field) Used by Jelly to abstract away the handling of global.jelly vs config.jelly databinding difference.
Descriptor.PropertyType	getPropertyType(String field) Obtains the property type of the given field of clazz
Descriptor.PropertyType	getPropertyTypeOrDie(Object instance, String field) Akin to getPropertyType(Object,String) but never returns null.
Permission	getRequiredGlobalConfigPagePermission() Returns the permission type needed in order to access the getGlobalConfigPage() for this descriptor.
Class<T>	getT() Unlike clazz, return the parameter type 'T', which determines the DescriptorExtensionList that this goes to.
protected String	getViewPage(Class<?> clazz, String pageName)
boolean	isInstance(T instance) Checks if the given object is created from this Descriptor.
boolean	isSubTypeOf(Class type) Checks if the type represented by this descriptor is a subtype of the given type.
void	load() Loads the data from the disk into this object.
T	newInstance(org.kohsuke.stapler.StaplerRequest req) Deprecated. Implement newInstance(StaplerRequest, JSONObject) method instead. Deprecated as of 1.145.
T	newInstance(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject formData) Creates a configured instance from the submitted form.
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) Used to build Describable instance list from <f:hetero-list> tag.
static <T extends Describable<T>> List<T>	newInstancesFromHeteroList(org.kohsuke.stapler.StaplerRequest req, Object formData, Collection<? extends Descriptor<T>> descriptors)
void	save() Saves the configuration info to the disk.
protected static Class	self()
static <T> T[]	toArray(T... values)
static <T> List<T>	toList(T... values)
static <T extends Describable<T>> Map<Descriptor<T>,T>	toMap(Iterable<T> describables)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.

getDescriptorUrl

public String getDescriptorUrl()

Gets the URL that this Descriptor is bound to, relative to the nearest DescriptorByNameOwner. Since Jenkins is a DescriptorByNameOwner, there's always one such ancestor to any request.

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

getCheckUrl

@Deprecated
public String getCheckUrl(String fieldName)

Deprecated. since 1.528 Use getCheckMethod(String)

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.

getPropertyTypeOrDie

@NonNull
public Descriptor.PropertyType getPropertyTypeOrDie(@NonNull
                                                             Object instance,
                                                             @NonNull
                                                             String field)

Akin to getPropertyType(Object,String) but never returns null.

Throws:

AssertionError - in case the field cannot be found

Since:

1.492

getPropertyType

public Descriptor.PropertyType getPropertyType(String field)

Obtains the property type of the given field of clazz

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

@Deprecated
public T newInstance(org.kohsuke.stapler.StaplerRequest req)
                          throws Descriptor.FormException

Deprecated. Implement newInstance(StaplerRequest, JSONObject) method instead. Deprecated as of 1.145.

Throws:

Descriptor.FormException

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.

Starting 1.206, the default implementation of this method does the following:

 req.bindJSON(clazz,formData);
 

... 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 http://wiki.jenkins-ci.org/display/JENKINS/Structured+Form+Submission 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

@Deprecated
public boolean configure(org.kohsuke.stapler.StaplerRequest req)
                              throws Descriptor.FormException

Deprecated. As of 1.239, use configure(StaplerRequest, JSONObject).

Throws:

Descriptor.FormException

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 http://wiki.jenkins-ci.org/display/JENKINS/Structured+Form+Submission

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.)

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

toArray

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

toList

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

toMap

public static <T extends Describable<T>> Map<Descriptor<T>,T> toMap(Iterable<T> describables)

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

newInstancesFromHeteroList

public static <T extends Describable<T>> List<T> newInstancesFromHeteroList(org.kohsuke.stapler.StaplerRequest req,
                                                                            Object formData,
                                                                            Collection<? extends Descriptor<T>> descriptors)
                                                                     throws Descriptor.FormException

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

find

@Deprecated
 @CheckForNull
public static <T extends Descriptor> T find(Collection<? extends T> list,
                                                                       String string)

Deprecated. choose between findById(java.util.Collection<? extends T>, java.lang.String) or findByDescribableClassName(java.util.Collection<? extends T>, java.lang.String)

Finds a descriptor from a collection by its class name or ID.

find

@Deprecated
 @CheckForNull
public static Descriptor find(String className)

Deprecated. choose between findById(java.util.Collection<? extends T>, java.lang.String) or findByDescribableClassName(java.util.Collection<? extends T>, java.lang.String)

self

protected static Class self()