org.mapstruct

Annotation Type Mapping

@Retention(value=CLASS)
 @Target(value=METHOD)
public @interface Mapping

Configures the mapping of one bean attribute or enum constant.

The name of the mapped attribute or constant is to be specified via target(). For mapped bean attributes it is assumed by default that the attribute has the same name in the source bean. Alternatively, one of source(), expression() or constant() can be specified to define the property source.

In addition, the attributes dateFormat() and qualifiedBy() may be used to further define the mapping.

IMPORTANT NOTE: the enum mapping capability is deprecated and replaced by ValueMapping it will be removed in subsequent versions.

Author:

Gunnar Morling

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	target The target name of the configured property as defined by the JavaBeans specification.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	constant A constant String based on which the specified target property is to be set.
String	dateFormat A format string as processable by SimpleDateFormat if the attribute is mapped from String to Date or vice-versa.
String	defaultValue In case the source property is null, the provided default String value is set.
String[]	dependsOn One or more properties of the result type on which the mapped property depends.
String	expression An expression String based on which the specified target property is to be set.
boolean	ignore Whether the property specified via target() should be ignored by the generated mapping method or not.
String	numberFormat A format string as processable by DecimalFormat if the annotated method maps from a Number to a String or vice-versa.
Class<? extends Annotation>[]	qualifiedBy A qualifier can be specified to aid the selection process of a suitable mapper.
String[]	qualifiedByName String-based form of qualifiers; When looking for a suitable mapping method for a given property, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the class-level) a Named annotation for each of the specified qualifier names.
Class<?>	resultType Specifies the result type of the mapping method to be used in case multiple mapping methods qualify.
String	source The source to use for this mapping.

Element Detail

target

public abstract String target

The target name of the configured property as defined by the JavaBeans specification. The same target property must not be mapped more than once.

If used to map an enum constant, the name of the constant member is to be given. In this case, several values from the source enum may be mapped to the same value of the target enum.

Returns:

The target name of the configured property or enum constant

source

public abstract String source

The source to use for this mapping. This can either be:

1. The source name of the configured property as defined by the JavaBeans specification.

   This may either be a simple property name (e.g. "address") or a dot-separated property path (e.g. "address.city" or "address.city.name"). In case the annotated method has several source parameters, the property name must qualified with the parameter name, e.g. "addressParam.city".

2. When no matching property is found, MapStruct looks for a matching parameter name instead.
3. When used to map an enum constant, the name of the constant member is to be given.

This attribute can not be used together with constant() or expression().

Returns:

The source name of the configured property or enum constant.

Default:

""

dateFormat

public abstract String dateFormat

A format string as processable by SimpleDateFormat if the attribute is mapped from String to Date or vice-versa. Will be ignored for all other attribute types and when mapping enum constants.

Returns:

A date format string as processable by SimpleDateFormat.

Default:

""

numberFormat

public abstract String numberFormat

A format string as processable by DecimalFormat if the annotated method maps from a Number to a String or vice-versa. Will be ignored for all other element types.

Returns:

A decimal format string as processable by DecimalFormat.

Default:

""

constant

public abstract String constant

A constant String based on which the specified target property is to be set. If the designated target property is not of type String, the value will be converted by applying a matching conversion method or built-in conversion.

This attribute can not be used together with source(), defaultValue() or expression().

Returns:

A constant String constant specifying the value for the designated target property

Default:

""

expression

public abstract String expression

An expression String based on which the specified target property is to be set.

Currently, Java is the only supported "expression language" and expressions must be given in form of Java expressions using the following format: java(<EXPRESSION>). For instance the mapping:

 @Mapping(
     target = "someProp",
     expression = "java(new TimeAndFormat( s.getTime(), s.getFormat() ))"
 )
 

will cause the following target property assignment to be generated:

targetBean.setSomeProp( new TimeAndFormat( s.getTime(), s.getFormat() ) ).

Any types referenced in expressions must be given via their fully-qualified name. Alternatively, types can be imported via Mapper.imports().

This attribute can not be used together with source(), defaultValue() or constant().

Returns:

An expression specifying the value for the designated target property

Default:

""

ignore

public abstract boolean ignore

Whether the property specified via target() should be ignored by the generated mapping method or not. This can be useful when certain attributes should not be propagated from source or target or when properties in the target object are populated using a decorator and thus would be reported as unmapped target property by default.

Returns:

true if the given property should be ignored, false otherwise

Default:

false

qualifiedBy

public abstract Class<? extends Annotation>[] qualifiedBy

A qualifier can be specified to aid the selection process of a suitable mapper. This is useful in case multiple mapping methods (hand written or generated) qualify and thus would result in an 'Ambiguous mapping methods found' error. A qualifier is a custom annotation and can be placed on a hand written mapper class or a method.

Returns:

the qualifiers

Default:

{}

qualifiedByName

public abstract String[] qualifiedByName

String-based form of qualifiers; When looking for a suitable mapping method for a given property, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the class-level) a Named annotation for each of the specified qualifier names.

Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large number of qualifiers as no custom annotation types are needed.

Returns:

One or more qualifier name(s)

See Also:

qualifiedBy(), Named

Default:

{}

resultType

public abstract Class<?> resultType

Specifies the result type of the mapping method to be used in case multiple mapping methods qualify.

Returns:

the resultType to select

Default:

void.class

dependsOn

public abstract String[] dependsOn

One or more properties of the result type on which the mapped property depends. The generated method implementation will invoke the setters of the result type ordered so that the given dependency relationship(s) are satisfied. Useful in case one property setter depends on the state of another property of the result type.

An error will be raised in case a cycle in the dependency relationships is detected.

Returns:

the dependencies of the mapped property

Default:

{}

defaultValue

public abstract String defaultValue

In case the source property is null, the provided default String value is set. If the designated target property is not of type String, the value will be converted by applying a matching conversion method or built-in conversion.

This attribute can not be used together with constant() or expression().

Returns:

Default value to set in case the source property is null.

Default:

""