hudson.model
Class Descriptor<T extends Describable<T>>

java.lang.Object
  hudson.model.Descriptor<T>

All Implemented Interfaces:

Saveable

Direct Known Subclasses:

AbstractNodeMonitorDescriptor, AuthorizationStrategy.Unsecured.DescriptorImpl, AxisDescriptor, BuildStepDescriptor, BuildWrapperDescriptor, CaptchaSupportDescriptor, CommandLauncher.DescriptorImpl, ComputerConnectorDescriptor, ConsoleAnnotationDescriptor, CrumbIssuerDescriptor, DelegatingComputerLauncher.DescriptorImpl, FileSystemProvisionerDescriptor, GlobalMatrixAuthorizationStrategy.DescriptorImpl, GraphSupportDescriptor, HudsonPrivateSecurityRealm.DescriptorImpl, JobPropertyDescriptor, LabelAtomPropertyDescriptor, LDAPSecurityRealm.DescriptorImpl, ListViewColumnDescriptor, LogRotator.LRDescriptor, MarkupFormatterDescriptor, MyViewsTabBarDescriptor, NativeMacSupportDescriptor, NativeUnixSupportDescriptor, NativeWindowsSupportDescriptor, NativeZfsSupportDescriptor, NodeDescriptor, PageDecorator, PAMSecurityRealm.DescriptorImpl, ParameterDefinition.ParameterDescriptor, PropertyDescriptor, RetentionStrategy.Always.DescriptorImpl, RetentionStrategy.Demand.DescriptorImpl, SCMDescriptor, ScriptSupportDescriptor, SimpleScheduledRetentionStrategy.DescriptorImpl, ToolDescriptor, ToolInstallerDescriptor, TopLevelItemDescriptor, TriggerDescriptor, UserPropertyDescriptor, ViewDescriptor, ViewsTabBarDescriptor

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

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

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

static class	Descriptor.FormException
static class	Descriptor.PropertyType Represents a readable property on Describable.

Field Summary

Class<? extends T>

clazz The class being described by this descriptor.

Fields inherited from interface hudson.model.Saveable

NOOP

Method Summary

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 className) Finds a descriptor from a collection by its class name.
static Descriptor	find(String className)
String	getCheckUrl(String fieldName) If the field "xyz" of a Describable has the corresponding "doCheckXyz" method, return the form-field validation string.
XmlFile	getConfigFile()
String	getConfigPage()
String	getDescriptorUrl() Gets the URL that this Descriptor is bound to, relative to the nearest DescriptorByNameOwner.
abstract 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(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.
Descriptor.PropertyType	getPropertyType(Object instance, String field) Used by Jelly to abstract away the handlign of global.jelly vs config.jelly databinding difference.
Descriptor.PropertyType	getPropertyType(String field) Obtains the property type of the given field of clazz
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.
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

equals, 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.

Method Detail

getDisplayName

public abstract String getDisplayName()

Human readable name of this kind of configurable object.

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.

Returns:

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

Since:

1.391

getDescriptorUrl

public String getDescriptorUrl()

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

getCheckUrl

public String getCheckUrl(String fieldName)

If the field "xyz" of a Describable has the corresponding "doCheckXyz" method, return the form-field validation string. Otherwise null.

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

public Descriptor.PropertyType getPropertyType(Object instance,
                                               String field)

Used by Jelly to abstract away the handlign of global.jelly vs config.jelly databinding difference.

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

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(org.kohsuke.stapler.StaplerRequest req,
                     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.hudson-ci.org/display/HUDSON/Structured+Form+Submission Always non-null.

Throws:

Descriptor.FormException - Signals a problem in the submitted form.

Since:

1.145

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.

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)
                  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 overriden to store descriptor-specific information.

Parameters:

json - The JSON object that captures the configuration data for this Descriptor. See http://wiki.hudson-ci.org/display/HUDSON/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()

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

public XmlFile getConfigFile()

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

find

public static <T extends Descriptor> T find(Collection<? extends T> list,
                                            String className)

Finds a descriptor from a collection by its class name.

find

public static Descriptor find(String className)