Package org.jenkinsci.plugins.structs.describable

Class DescribableModel<T>

java.lang.Object

org.jenkinsci.plugins.structs.describable.DescribableModel<T>

All Implemented Interfaces:

Serializable

public final class DescribableModel<T>
extends Object
implements Serializable

Introspects a Describable with DataBoundConstructor and DataBoundSetter.

Provides such operations like

• instantiate this class from a JSON-like map
• take an existing instance and produces a JSON-like map that can be then fed back to the above instantiation call
• enumerate parameters of this Describable that are defined either through DataBoundConstructor or DataBoundSetter. See DescribableParameter for more details
• access help file

Note that some structures are recursive or mutually recursive. It is up a caller to defend against stack overflows when traversing a model graph, for example by keeping a stack of types which have already been encountered.

Author:

Jesse Glick, Andrew Bayer, Kohsuke Kawaguchi

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CLAZZ
static boolean	STRICT_PARAMETER_CHECKING

Constructor Summary

Constructors

Constructor	Description
DescribableModel(Class<T> clazz)	Loads a definition of the structure of a class: what kind of data you might get back from uninstantiate(T) on an instance, or might want to pass to instantiate(Map).

Method Summary

Modifier and Type	Method	Description
String	getDisplayName()	Corresponds to Descriptor.getDisplayName() where available.
DescribableParameter	getFirstRequiredParameter()	If this model has any required parameter, return the first one.
String	getHelp()	Loads help defined for this object as a whole
DescribableParameter	getParameter(String name)
Collection<DescribableParameter>	getParameters()	A map from parameter names to types.
DescribableParameter	getSoleRequiredParameter()	If this model has one and only one required parameter, return it.
Class<T>	getType()	A concrete class, usually Describable.
boolean	hasSingleRequiredParameter()	Returns true if this model has one and only one required parameter.
T	instantiate(Map<String,?> arguments)	Deprecated. instead use instantiate(Map, TaskListener)
T	instantiate(Map<String,?> arguments, TaskListener listener)	Creates an instance of a class via DataBoundConstructor and DataBoundSetter.
boolean	isDeprecated()	True if this model's type is deprecated.
static <T> DescribableModel<T>	of(Class<T> clazz)	Binds type parameter, preferred means of obtaining a DescribableModel.
String	toString()
Map<String,Object>	uninstantiate(T o)	Deprecated. as of 1.2 Use uninstantiate2(Object)
static Map<String,Object>	uninstantiate_(Object o)	Deprecated. as of 1.2.
UninstantiatedDescribable	uninstantiate2(T o)	Disects a given instance into UninstantiatedDescribable that you can re-instantiate via UninstantiatedDescribable.instantiate().
static UninstantiatedDescribable	uninstantiate2_(Object o)	In case if you just need to uninstantiate one object and be done with it.

Methods inherited from class java.lang.Object

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

Field Details

STRICT_PARAMETER_CHECKING

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static boolean STRICT_PARAMETER_CHECKING

CLAZZ

public static final String CLAZZ

See Also:

• Constant Field Values

Constructor Details

DescribableModel

public DescribableModel(Class<T> clazz)

Loads a definition of the structure of a class: what kind of data you might get back from uninstantiate(T) on an instance, or might want to pass to instantiate(Map). Use of(Class) instead -- that will returned cached instances.

Method Details

of

public static <T> DescribableModel<T> of(Class<T> clazz)

Binds type parameter, preferred means of obtaining a DescribableModel.

getType

public Class<T> getType()

A concrete class, usually Describable.

getParameters

public Collection<DescribableParameter> getParameters()

A map from parameter names to types. A parameter name is either the name of an argument to a DataBoundConstructor, or the JavaBeans property name corresponding to a DataBoundSetter.

Sorted by the mandatory parameters first (in the order they are specified in the code), followed by optional arguments.

getParameter

public DescribableParameter getParameter(String name)

hasSingleRequiredParameter

public boolean hasSingleRequiredParameter()

Returns true if this model has one and only one required parameter.

See Also:

• UninstantiatedDescribable.ANONYMOUS_KEY

getSoleRequiredParameter

@CheckForNull
public DescribableParameter getSoleRequiredParameter()

If this model has one and only one required parameter, return it. Otherwise null.

See Also:

• UninstantiatedDescribable.ANONYMOUS_KEY

getFirstRequiredParameter

@CheckForNull
public DescribableParameter getFirstRequiredParameter()

If this model has any required parameter, return the first one. Otherwise null.

getDisplayName

public String getDisplayName()

Corresponds to Descriptor.getDisplayName() where available.

instantiate

@Deprecated
public T instantiate(Map<String,?> arguments)
              throws IllegalArgumentException

Deprecated.

instead use instantiate(Map, TaskListener)

Throws:

IllegalArgumentException

instantiate

public T instantiate(Map<String,?> arguments,
 @CheckForNull
 TaskListener listener)
              throws IllegalArgumentException

Creates an instance of a class via DataBoundConstructor and DataBoundSetter.

The arguments may be primitives (as wrappers) or Strings if that is their declared type. Characters, Enums, and URLs may be represented by Strings. Other object types may be passed in “raw” as well, but JSON-like structures are encouraged instead. Specifically a List may be used to represent any list- or array-valued argument. A Map with String keys may be used to represent any class which is itself data-bound. In that case the special key CLAZZ is used to specify the Class.getName(); or it may be omitted if the argument is declared to take a concrete type; or Class.getSimpleName() may be used in case the argument type is Describable and only one subtype is registered (as a Descriptor) with that simple name.

Parameters:

arguments - The arguments used to create the instance

listener - Listener to record any instantiation warnings

Returns:

The instantiated object

Throws:

IllegalArgumentException

uninstantiate

@Deprecated
public Map<String,Object> uninstantiate(T o)
                                 throws UnsupportedOperationException

Deprecated.

as of 1.2 Use uninstantiate2(Object)

Computes arguments suitable to pass to instantiate(java.util.Map<java.lang.String, ?>) to reconstruct this object.

Parameters:

o - a data-bound object

Returns:

constructor and/or setter parameters

Throws:

UnsupportedOperationException - if the class does not follow the expected structure

uninstantiate2

public UninstantiatedDescribable uninstantiate2(T o)
                                         throws UnsupportedOperationException

Disects a given instance into UninstantiatedDescribable that you can re-instantiate via UninstantiatedDescribable.instantiate().

Parameters:

o - a data-bound object

Returns:

constructor and/or setter parameters

Throws:

UnsupportedOperationException - if the class does not follow the expected structure

uninstantiate_

@Deprecated
public static Map<String,Object> uninstantiate_(Object o)

Deprecated.

as of 1.2. Use uninstantiate2_(Object)

In case if you just need to uninstantiate one object and be done with it.

uninstantiate2_

public static UninstantiatedDescribable uninstantiate2_(Object o)

In case if you just need to uninstantiate one object and be done with it.

isDeprecated

public boolean isDeprecated()

True if this model's type is deprecated. A model is deprecated if it's type is marked as Deprecated.

getHelp

@CheckForNull
public String getHelp()
               throws IOException

Loads help defined for this object as a whole

Returns:

some HTML (in English locale), if available, else null

Throws:

IOException

See Also:

• Descriptor.doHelp(org.kohsuke.stapler.StaplerRequest2, org.kohsuke.stapler.StaplerResponse2)

toString

public String toString()

Overrides:

toString in class Object