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

java.lang.Object
  extended by 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)


Copyright © 2004-2013 Hudson. All Rights Reserved.