org.springframework.core.convert

Class TypeDescriptor

java.lang.Object

org.springframework.core.convert.TypeDescriptor

public class TypeDescriptor
extends java.lang.Object

Context about a type to convert from or to.

Since:

3.0

Author:

Keith Donald, Andy Clement, Juergen Hoeller, Phillip Webb, Sam Brannen

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.annotation.Annotation[]	annotations
private TypeDescriptor	elementTypeDescriptor
(package private) static java.lang.annotation.Annotation[]	EMPTY_ANNOTATION_ARRAY
private TypeDescriptor	mapKeyTypeDescriptor
private TypeDescriptor	mapValueTypeDescriptor
private java.lang.Class<?>	type
private static java.util.Map<java.lang.Class<?>,TypeDescriptor>	typeDescriptorCache

Constructor Summary

Constructors

Modifier	Constructor and Description
(package private)	TypeDescriptor(AbstractDescriptor descriptor)
private	TypeDescriptor(java.lang.Class<?> type)
private	TypeDescriptor(java.lang.Class<?> collectionType, TypeDescriptor elementTypeDescriptor)
private	TypeDescriptor(java.lang.Class<?> mapType, TypeDescriptor keyTypeDescriptor, TypeDescriptor valueTypeDescriptor)
private	TypeDescriptor(java.lang.Class<?> type, TypeDescriptor elementTypeDescriptor, TypeDescriptor mapKeyTypeDescriptor, TypeDescriptor mapValueTypeDescriptor, java.lang.annotation.Annotation[] annotations)
	TypeDescriptor(java.lang.reflect.Field field) Create a new type descriptor from a Field.
	TypeDescriptor(MethodParameter methodParameter) Create a new type descriptor from a MethodParameter.
	TypeDescriptor(Property property) Create a new type descriptor from a Property.

Method Summary

Modifier and Type	Method and Description
static TypeDescriptor	array(TypeDescriptor elementTypeDescriptor) Create a new type descriptor as an array of the specified type.
private void	assertCollectionOrArray()
private void	assertMap()
static TypeDescriptor	collection(java.lang.Class<?> collectionType, TypeDescriptor elementTypeDescriptor) Create a new type descriptor from a Collection type.
TypeDescriptor	elementTypeDescriptor(java.lang.Object element) If this type is a Collection or an Array, creates a element TypeDescriptor from the provided collection or array element.
boolean	equals(java.lang.Object obj)
static TypeDescriptor	forObject(java.lang.Object source) Create a new type descriptor for an object.
<T extends java.lang.annotation.Annotation> T	getAnnotation(java.lang.Class<T> annotationType) Obtain the annotation associated with this type descriptor of the specified type.
java.lang.annotation.Annotation[]	getAnnotations() The annotations associated with this type descriptor, if any.
java.lang.Class<?>	getElementType() Deprecated. in Spring 3.1 in favor of getElementTypeDescriptor()
TypeDescriptor	getElementTypeDescriptor() If this type is an array, returns the array's component type.
java.lang.Class<?>	getMapKeyType() Deprecated. in Spring 3.1 in favor of getMapKeyTypeDescriptor()
TypeDescriptor	getMapKeyTypeDescriptor() If this type is a Map and its key type is parameterized, returns the map's key type.
TypeDescriptor	getMapKeyTypeDescriptor(java.lang.Object mapKey) If this type is a Map, creates a mapKey TypeDescriptor from the provided map key.
java.lang.Class<?>	getMapValueType() Deprecated. in Spring 3.1 in favor of getMapValueTypeDescriptor()
TypeDescriptor	getMapValueTypeDescriptor() If this type is a Map and its value type is parameterized, returns the map's value type.
TypeDescriptor	getMapValueTypeDescriptor(java.lang.Object mapValue) If this type is a Map, creates a mapValue TypeDescriptor from the provided map value.
java.lang.String	getName() Returns the name of this type: the fully qualified class name.
java.lang.Class<?>	getObjectType() Variation of getType() that accounts for a primitive type by returning its object wrapper type.
java.lang.Class<?>	getType() The type of the backing class, method parameter, field, or property described by this TypeDescriptor.
boolean	hasAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> annotationType) Determine if this type descriptor has the specified annotation.
int	hashCode()
boolean	isArray() Is this type an array type?
boolean	isAssignableTo(TypeDescriptor typeDescriptor) Returns true if an object of this type descriptor can be assigned to the location described by the given type descriptor.
boolean	isCollection() Is this type a Collection type?
boolean	isMap() Is this type a Map type?
private boolean	isNestedAssignable(TypeDescriptor nestedTypeDescriptor, TypeDescriptor otherNestedTypeDescriptor)
boolean	isPrimitive() Is this type a primitive type?
static TypeDescriptor	map(java.lang.Class<?> mapType, TypeDescriptor keyTypeDescriptor, TypeDescriptor valueTypeDescriptor) Create a new type descriptor from a Map type.
TypeDescriptor	narrow(java.lang.Object value) Narrows this TypeDescriptor by setting its type to the class of the provided value.
private TypeDescriptor	narrow(java.lang.Object value, TypeDescriptor typeDescriptor)
private static TypeDescriptor	nested(AbstractDescriptor descriptor, int nestingLevel)
static TypeDescriptor	nested(java.lang.reflect.Field field, int nestingLevel) Creates a type descriptor for a nested type declared within the field.
static TypeDescriptor	nested(MethodParameter methodParameter, int nestingLevel) Creates a type descriptor for a nested type declared within the method parameter.
static TypeDescriptor	nested(Property property, int nestingLevel) Creates a type descriptor for a nested type declared within the property.
(package private) static java.lang.annotation.Annotation[]	nullSafeAnnotations(java.lang.annotation.Annotation[] annotations)
java.lang.String	toString()
TypeDescriptor	upcast(java.lang.Class<?> superType) Cast this TypeDescriptor to a superclass or implemented interface preserving annotations and nested type context.
static TypeDescriptor	valueOf(java.lang.Class<?> type) Create a new type descriptor from the given type.
private java.lang.String	wildcard(TypeDescriptor typeDescriptor)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_ANNOTATION_ARRAY

static final java.lang.annotation.Annotation[] EMPTY_ANNOTATION_ARRAY

typeDescriptorCache

private static final java.util.Map<java.lang.Class<?>,TypeDescriptor> typeDescriptorCache

type

private final java.lang.Class<?> type

elementTypeDescriptor

private final TypeDescriptor elementTypeDescriptor

mapKeyTypeDescriptor

private final TypeDescriptor mapKeyTypeDescriptor

mapValueTypeDescriptor

private final TypeDescriptor mapValueTypeDescriptor

annotations

private final java.lang.annotation.Annotation[] annotations

Constructor Detail

TypeDescriptor

public TypeDescriptor(MethodParameter methodParameter)

Create a new type descriptor from a MethodParameter.

Use this constructor when a source or target conversion point is a constructor parameter, method parameter, or method return value.

Parameters:

methodParameter - the method parameter

TypeDescriptor

public TypeDescriptor(java.lang.reflect.Field field)

Create a new type descriptor from a Field.

Use this constructor when a source or target conversion point is a field.

Parameters:

field - the field

TypeDescriptor

public TypeDescriptor(Property property)

Create a new type descriptor from a Property.

Use this constructor when a source or target conversion point is a property on a Java class.

Parameters:

property - the property

TypeDescriptor

TypeDescriptor(AbstractDescriptor descriptor)

TypeDescriptor

private TypeDescriptor(java.lang.Class<?> type)

TypeDescriptor

private TypeDescriptor(java.lang.Class<?> collectionType,
              TypeDescriptor elementTypeDescriptor)

TypeDescriptor

private TypeDescriptor(java.lang.Class<?> mapType,
              TypeDescriptor keyTypeDescriptor,
              TypeDescriptor valueTypeDescriptor)

TypeDescriptor

private TypeDescriptor(java.lang.Class<?> type,
              TypeDescriptor elementTypeDescriptor,
              TypeDescriptor mapKeyTypeDescriptor,
              TypeDescriptor mapValueTypeDescriptor,
              java.lang.annotation.Annotation[] annotations)

Method Detail

valueOf

public static TypeDescriptor valueOf(java.lang.Class<?> type)

Create a new type descriptor from the given type.

Use this to instruct the conversion system to convert an object to a specific target type, when no type location such as a method parameter or field is available to provide additional conversion context.

Generally prefer use of forObject(Object) for constructing type descriptors from source objects, as it handles the null object case.

Parameters:

type - the class

Returns:

the type descriptor

collection

public static TypeDescriptor collection(java.lang.Class<?> collectionType,
                        TypeDescriptor elementTypeDescriptor)

Create a new type descriptor from a Collection type.

Useful for converting to typed Collections.

For example, a List<String> could be converted to a List<EmailAddress> by converting to a targetType built with this method. The method call to construct such a TypeDescriptor would look something like: collection(List.class, TypeDescriptor.valueOf(EmailAddress.class));

Parameters:

collectionType - the collection type, which must implement Collection.

elementTypeDescriptor - a descriptor for the collection's element type, used to convert collection elements

Returns:

the collection type descriptor

map

public static TypeDescriptor map(java.lang.Class<?> mapType,
                 TypeDescriptor keyTypeDescriptor,
                 TypeDescriptor valueTypeDescriptor)

Create a new type descriptor from a Map type.

Useful for converting to typed Maps.

For example, a Map<String, String> could be converted to a Map<Id, EmailAddress> by converting to a targetType built with this method: The method call to construct such a TypeDescriptor would look something like: map(Map.class, TypeDescriptor.valueOf(Id.class), TypeDescriptor.valueOf(EmailAddress.class));

Parameters:

mapType - the map type, which must implement Map

keyTypeDescriptor - a descriptor for the map's key type, used to convert map keys

valueTypeDescriptor - the map's value type, used to convert map values

Returns:

the map type descriptor

array

public static TypeDescriptor array(TypeDescriptor elementTypeDescriptor)

Create a new type descriptor as an array of the specified type.

For example to create a Map<String,String>[] use TypeDescriptor.array(TypeDescriptor.map(Map.class, TypeDescriptor.value(String.class), TypeDescriptor.value(String.class))).

Parameters:

elementTypeDescriptor - the TypeDescriptor of the array element or null

Returns:

an array TypeDescriptor or null if elementTypeDescriptor is null

Since:

3.2.1

nested

public static TypeDescriptor nested(MethodParameter methodParameter,
                    int nestingLevel)

Creates a type descriptor for a nested type declared within the method parameter.

For example, if the methodParameter is a List<String> and the nesting level is 1, the nested type descriptor will be String.class.

If the methodParameter is a List<List<String>> and the nesting level is 2, the nested type descriptor will also be a String.class.

If the methodParameter is a Map<Integer, String> and the nesting level is 1, the nested type descriptor will be String, derived from the map value.

If the methodParameter is a List<Map<Integer, String>> and the nesting level is 2, the nested type descriptor will be String, derived from the map value.

Returns null if a nested type cannot be obtained because it was not declared. For example, if the method parameter is a List<?>, the nested type descriptor returned will be null.

Parameters:

methodParameter - the method parameter with a nestingLevel of 1

nestingLevel - the nesting level of the collection/array element or map key/value declaration within the method parameter

Returns:

the nested type descriptor at the specified nesting level, or null if it could not be obtained

Throws:

java.lang.IllegalArgumentException - if the nesting level of the input MethodParameter argument is not 1

java.lang.IllegalArgumentException - if the types up to the specified nesting level are not of collection, array, or map types

nested

public static TypeDescriptor nested(java.lang.reflect.Field field,
                    int nestingLevel)

Creates a type descriptor for a nested type declared within the field.

For example, if the field is a List<String> and the nesting level is 1, the nested type descriptor will be String.class.

If the field is a List<List<String>> and the nesting level is 2, the nested type descriptor will also be a String.class.

If the field is a Map<Integer, String> and the nesting level is 1, the nested type descriptor will be String, derived from the map value.

If the field is a List<Map<Integer, String>> and the nesting level is 2, the nested type descriptor will be String, derived from the map value.

Returns null if a nested type cannot be obtained because it was not declared. For example, if the field is a List<?>, the nested type descriptor returned will be null.

Parameters:

field - the field

nestingLevel - the nesting level of the collection/array element or map key/value declaration within the field

Returns:

the nested type descriptor at the specified nesting level, or null if it could not be obtained

Throws:

java.lang.IllegalArgumentException - if the types up to the specified nesting level are not of collection, array, or map types

nested

public static TypeDescriptor nested(Property property,
                    int nestingLevel)

Creates a type descriptor for a nested type declared within the property.

For example, if the property is a List<String> and the nesting level is 1, the nested type descriptor will be String.class.

If the property is a List<List<String>> and the nesting level is 2, the nested type descriptor will also be a String.class.

If the property is a Map<Integer, String> and the nesting level is 1, the nested type descriptor will be String, derived from the map value.

If the property is a List<Map<Integer, String>> and the nesting level is 2, the nested type descriptor will be String, derived from the map value.

Returns null if a nested type cannot be obtained because it was not declared. For example, if the property is a List<?>, the nested type descriptor returned will be null.

Parameters:

property - the property

nestingLevel - the nesting level of the collection/array element or map key/value declaration within the property

Returns:

the nested type descriptor at the specified nesting level, or null if it could not be obtained

Throws:

java.lang.IllegalArgumentException - if the types up to the specified nesting level are not of collection, array, or map types

forObject

public static TypeDescriptor forObject(java.lang.Object source)

Create a new type descriptor for an object.

Use this factory method to introspect a source object before asking the conversion system to convert it to some another type.

If the provided object is null, returns null, else calls valueOf(Class) to build a TypeDescriptor from the object's class.

Parameters:

source - the source object

Returns:

the type descriptor

getType

public java.lang.Class<?> getType()

The type of the backing class, method parameter, field, or property described by this TypeDescriptor.

Returns primitive types as-is.

See getObjectType() for a variation of this operation that resolves primitive types to their corresponding Object types if necessary.

Returns:

the type, or null

See Also:

getObjectType()

getObjectType

public java.lang.Class<?> getObjectType()

Variation of getType() that accounts for a primitive type by returning its object wrapper type.

This is useful for conversion service implementations that wish to normalize to object-based types and not work with primitive types directly.

narrow

public TypeDescriptor narrow(java.lang.Object value)

Narrows this TypeDescriptor by setting its type to the class of the provided value.

If the value is null, no narrowing is performed and this TypeDescriptor is returned unchanged.

Designed to be called by binding frameworks when they read property, field, or method return values. Allows such frameworks to narrow a TypeDescriptor built from a declared property, field, or method return value type. For example, a field declared as java.lang.Object would be narrowed to java.util.HashMap if it was set to a java.util.HashMap value. The narrowed TypeDescriptor can then be used to convert the HashMap to some other type. Annotation and nested type context is preserved by the narrowed copy.

Parameters:

value - the value to use for narrowing this type descriptor

Returns:

this TypeDescriptor narrowed (returns a copy with its type updated to the class of the provided value)

upcast

public TypeDescriptor upcast(java.lang.Class<?> superType)

Cast this TypeDescriptor to a superclass or implemented interface preserving annotations and nested type context.

Parameters:

superType - the super type to cast to (can be null

Returns:

a new TypeDescriptor for the up-cast type

Throws:

java.lang.IllegalArgumentException - if this type is not assignable to the super-type

Since:

3.2

getName

public java.lang.String getName()

Returns the name of this type: the fully qualified class name.

isPrimitive

public boolean isPrimitive()

Is this type a primitive type?

getAnnotations

public java.lang.annotation.Annotation[] getAnnotations()

The annotations associated with this type descriptor, if any.

Returns:

the annotations, or an empty array if none

hasAnnotation

public boolean hasAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)

Determine if this type descriptor has the specified annotation.

Parameters:

annotationType - the annotation type

Returns:

true if the annotation is present

getAnnotation

public <T extends java.lang.annotation.Annotation> T getAnnotation(java.lang.Class<T> annotationType)

Obtain the annotation associated with this type descriptor of the specified type.

Parameters:

annotationType - the annotation type

Returns:

the annotation, or null if no such annotation exists on this type descriptor

isAssignableTo

public boolean isAssignableTo(TypeDescriptor typeDescriptor)

Returns true if an object of this type descriptor can be assigned to the location described by the given type descriptor.

For example, valueOf(String.class).isAssignableTo(valueOf(CharSequence.class)) returns true because a String value can be assigned to a CharSequence variable. On the other hand, valueOf(Number.class).isAssignableTo(valueOf(Integer.class)) returns false because, while all Integers are Numbers, not all Numbers are Integers.

For arrays, collections, and maps, element and key/value types are checked if declared. For example, a List<String> field value is assignable to a Collection<CharSequence> field, but List<Number> is not assignable to List<Integer>.

Returns:

true if this type is assignable to the type represented by the provided type descriptor

See Also:

getObjectType()

isCollection

public boolean isCollection()

Is this type a Collection type?

isArray

public boolean isArray()

Is this type an array type?

getElementTypeDescriptor

public TypeDescriptor getElementTypeDescriptor()

If this type is an array, returns the array's component type. If this type is a Collection and it is parameterized, returns the Collection's element type. If the Collection is not parameterized, returns null indicating the element type is not declared.

Returns:

the array component type or Collection element type, or null if this type is a Collection but its element type is not parameterized

Throws:

java.lang.IllegalStateException - if this type is not a java.util.Collection or Array type

elementTypeDescriptor

public TypeDescriptor elementTypeDescriptor(java.lang.Object element)

If this type is a Collection or an Array, creates a element TypeDescriptor from the provided collection or array element.

Narrows the elementType property to the class of the provided collection or array element. For example, if this describes a java.util.List<java.lang.Number< and the element argument is a java.lang.Integer, the returned TypeDescriptor will be java.lang.Integer. If this describes a java.util.List<?> and the element argument is a java.lang.Integer, the returned TypeDescriptor will be java.lang.Integer as well.

Annotation and nested type context will be preserved in the narrowed TypeDescriptor that is returned.

Parameters:

element - the collection or array element

Returns:

a element type descriptor, narrowed to the type of the provided element

Throws:

java.lang.IllegalStateException - if this type is not a java.util.Collection or Array type

See Also:

narrow(Object)

isMap

public boolean isMap()

Is this type a Map type?

getMapKeyTypeDescriptor

public TypeDescriptor getMapKeyTypeDescriptor()

If this type is a Map and its key type is parameterized, returns the map's key type. If the Map's key type is not parameterized, returns null indicating the key type is not declared.

Returns:

the Map key type, or null if this type is a Map but its key type is not parameterized

Throws:

java.lang.IllegalStateException - if this type is not a java.util.Map

getMapKeyTypeDescriptor

public TypeDescriptor getMapKeyTypeDescriptor(java.lang.Object mapKey)

If this type is a Map, creates a mapKey TypeDescriptor from the provided map key.

Narrows the mapKeyType property to the class of the provided map key. For example, if this describes a java.util.Map<java.lang.Number, java.lang.String< and the key argument is a java.lang.Integer, the returned TypeDescriptor will be java.lang.Integer.

If this describes a java.util.Map<?, ?> and the key argument is a java.lang.Integer, the returned TypeDescriptor will be java.lang.Integer as well.

Annotation and nested type context will be preserved in the narrowed TypeDescriptor that is returned.

Parameters:

mapKey - the map key

Returns:

the map key type descriptor

Throws:

java.lang.IllegalStateException - if this type is not a java.util.Map

See Also:

narrow(Object)

getMapValueTypeDescriptor

public TypeDescriptor getMapValueTypeDescriptor()

If this type is a Map and its value type is parameterized, returns the map's value type.

If the Map's value type is not parameterized, returns null indicating the value type is not declared.

Returns:

the Map value type, or null if this type is a Map but its value type is not parameterized

Throws:

java.lang.IllegalStateException - if this type is not a java.util.Map

getMapValueTypeDescriptor

public TypeDescriptor getMapValueTypeDescriptor(java.lang.Object mapValue)

If this type is a Map, creates a mapValue TypeDescriptor from the provided map value.

Narrows the mapValueType property to the class of the provided map value. For example, if this describes a java.util.Map<java.lang.String, java.lang.Number< and the value argument is a java.lang.Integer, the returned TypeDescriptor will be java.lang.Integer. If this describes a java.util.Map<?, ?> and the value argument is a java.lang.Integer, the returned TypeDescriptor will be java.lang.Integer as well.

Annotation and nested type context will be preserved in the narrowed TypeDescriptor that is returned.

Parameters:

mapValue - the map value

Returns:

the map value type descriptor

Throws:

java.lang.IllegalStateException - if this type is not a java.util.Map

getElementType

@Deprecated
public java.lang.Class<?> getElementType()

Deprecated. in Spring 3.1 in favor of getElementTypeDescriptor()

Returns the value of getType() for the elementTypeDescriptor.

Throws:

java.lang.IllegalStateException - if this type is not a java.util.Collection or Array type

getMapKeyType

@Deprecated
public java.lang.Class<?> getMapKeyType()

Deprecated. in Spring 3.1 in favor of getMapKeyTypeDescriptor()

Returns the value of getType() for the getMapKeyTypeDescriptor.

Throws:

java.lang.IllegalStateException - if this type is not a java.util.Map

getMapValueType

@Deprecated
public java.lang.Class<?> getMapValueType()

Deprecated. in Spring 3.1 in favor of getMapValueTypeDescriptor()

Returns the value of getType() for the getMapValueTypeDescriptor.

Throws:

java.lang.IllegalStateException - if this type is not a java.util.Map

nullSafeAnnotations

static java.lang.annotation.Annotation[] nullSafeAnnotations(java.lang.annotation.Annotation[] annotations)

nested

private static TypeDescriptor nested(AbstractDescriptor descriptor,
                    int nestingLevel)

assertCollectionOrArray

private void assertCollectionOrArray()

assertMap

private void assertMap()

narrow

private TypeDescriptor narrow(java.lang.Object value,
                    TypeDescriptor typeDescriptor)

isNestedAssignable

private boolean isNestedAssignable(TypeDescriptor nestedTypeDescriptor,
                         TypeDescriptor otherNestedTypeDescriptor)

wildcard

private java.lang.String wildcard(TypeDescriptor typeDescriptor)

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object