public abstract class Descriptor<T extends Describable<T>> extends Object implements Saveable, OnMaster
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.
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
.
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.Describable
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. |
Modifier and Type | Field and Description |
---|---|
Class<? extends T> |
clazz
The class being described by this descriptor.
|
Modifier | Constructor and Description |
---|---|
protected |
Descriptor()
Infers the type of the corresponding
Describable from the outer class. |
protected |
Descriptor(Class<? extends T> clazz) |
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.
|
static <T> T |
bindJSON(org.kohsuke.stapler.StaplerRequest req,
Class<T> type,
net.sf.json.JSONObject src)
Replacement for
StaplerRequest.bindJSON(Class, JSONObject) which honors newInstance(StaplerRequest, JSONObject) . |
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> |
find(Collection<? extends T> list,
String string)
|
static Descriptor |
find(String className)
|
static <T extends Descriptor> |
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> |
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 Descriptor s. |
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>> |
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>> |
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>> |
toMap(Iterable<T> describables) |
public final transient Class<? extends T extends Describable<T>> clazz
protected Descriptor(Class<? extends T> clazz)
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.protected Descriptor()
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.@NonNull public String getDisplayName()
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
.public String getId()
Descriptor
among all the other Descriptor
s.
Historically clazz
is assumed to be unique, so this method uses that as the default,
but if you are adding Descriptor
s programmatically for the same type, you can change
this to disambiguate them.
To look up Descriptor
from ID, use Jenkins.getDescriptor(String)
.
public Class<T> getT()
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.
public String getDescriptorUrl()
DescriptorByNameOwner
.
Since Jenkins
is a DescriptorByNameOwner
, there's always one such ancestor to any request.public final String getDescriptorFullUrl()
public static String getCurrentDescriptorByNameUrl()
@Deprecated public String getCheckUrl(String fieldName)
getCheckMethod(String)
public FormValidation.CheckMethod getCheckMethod(String fieldName)
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.
public void calcFillSettings(String field, Map<String,Object> attributes)
public void calcAutoCompleteSettings(String field, Map<String,Object> attributes)
@CheckForNull public Descriptor.PropertyType getPropertyType(@NonNull Object instance, @NonNull String field)
@NonNull public Descriptor.PropertyType getPropertyTypeOrDie(@NonNull Object instance, @NonNull String field)
getPropertyType(Object,String)
but never returns null.AssertionError
- in case the field cannot be foundpublic Descriptor.PropertyType getPropertyType(String field)
clazz
public Descriptor.PropertyType getGlobalPropertyType(String field)
public final String getJsonSafeClassName()
@Deprecated public T newInstance(org.kohsuke.stapler.StaplerRequest req) throws Descriptor.FormException
newInstance(StaplerRequest, JSONObject)
method instead.
Deprecated as of 1.145.Descriptor.FormException
public T newInstance(@Nullable org.kohsuke.stapler.StaplerRequest req, @NonNull net.sf.json.JSONObject formData) throws Descriptor.FormException
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.
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 https://www.jenkins.io/doc/developer/forms/structured-form-submission/
Always non-null.Descriptor.FormException
- Signals a problem in the submitted form.public static <T> T bindJSON(org.kohsuke.stapler.StaplerRequest req, Class<T> type, net.sf.json.JSONObject src)
StaplerRequest.bindJSON(Class, JSONObject)
which honors newInstance(StaplerRequest, JSONObject)
.
This is automatically used inside newInstance(StaplerRequest, JSONObject)
so a direct call would only be necessary
in case the top level binding might use a Descriptor
which overrides newInstance(StaplerRequest, JSONObject)
.public org.kohsuke.stapler.lang.Klass<?> getKlass()
Klass
object used for the purpose of loading resources from this descriptor.
This hook enables other JVM languages to provide more integrated lookup.public String getHelpFile()
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()
.
public String getHelpFile(String fieldName)
The help files are assumed to be at "help/FIELDNAME.html" with possible locale variations.
protected void addHelpFileRedirect(String fieldName, Class<? extends Describable> owner, String fieldNameToRedirectTo)
public final boolean isInstance(T instance)
Descriptor
.public final boolean isSubTypeOf(Class type)
@Deprecated public boolean configure(org.kohsuke.stapler.StaplerRequest req) throws Descriptor.FormException
configure(StaplerRequest, JSONObject)
.Descriptor.FormException
public boolean configure(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject json) throws Descriptor.FormException
json
- The JSON object that captures the configuration data for this Descriptor
.
See https://www.jenkins.io/doc/developer/forms/structured-form-submission/Descriptor.FormException
public String getConfigPage()
public String getGlobalConfigPage()
@NonNull public GlobalConfigurationCategory getCategory()
Descriptor
.GlobalConfiguration
before that.@NonNull public Permission getRequiredGlobalConfigPagePermission()
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
.public void save()
public void load()
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.)
protected XmlFile getConfigFile()
protected PluginWrapper getPlugin()
public void doHelp(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException, javax.servlet.ServletException
help.html
from the resource of clazz
.IOException
javax.servlet.ServletException
public static <T> T[] toArray(T... values)
public static <T> List<T> toList(T... values)
public static <T extends Describable<T>> Map<Descriptor<T>,T> toMap(Iterable<T> describables)
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
Describable
instance list from <f:hetero-list>
tag.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.Descriptor.FormException
public static <T extends Describable<T>> List<T> newInstancesFromHeteroList(org.kohsuke.stapler.StaplerRequest req, Object formData, Collection<? extends Descriptor<T>> descriptors) throws Descriptor.FormException
Descriptor.FormException
@CheckForNull public static <T extends Descriptor> T findById(Collection<? extends T> list, String id)
id
- should match getId()
@CheckForNull public static <T extends Descriptor> T findByDescribableClassName(Collection<? extends T> list, String className)
Describable
it describes.className
- should match Class.getName()
of a clazz
@Deprecated @CheckForNull public static <T extends Descriptor> T find(Collection<? extends T> list, String string)
findById(java.util.Collection<? extends T>, java.lang.String)
or findByDescribableClassName(java.util.Collection<? extends T>, java.lang.String)
@Deprecated @CheckForNull public static Descriptor find(String className)
protected static Class self()
Copyright © 2004–2022. All rights reserved.