third_codes/mapstruct
1
0
Fork 0
mirror of https://github.com/mapstruct/mapstruct.git synced 2025-07-12 00:00:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

#750 Further expanding comment

Browse Source
This commit is contained in:
Gunnar Morling 2016-02-20 11:42:47 +01:00
parent e039c74c2a
commit 5e88dae8ce
5 changed files with 85 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
core-common/src/main/java/org/mapstruct/IterableMapping.java
View File

@ -57,11 +57,17 @@ public @interface IterableMapping {
Class<? extends Annotation>[] qualifiedBy() default { };
/**
* See: { @link #qualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
* is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
* is no need to define own annotations.
* String-based form of qualifiers; When looking for a suitable mapping method to map this iterable mapping method's
* element type, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the
* class-level) a {@link Named} annotation for each of the specified qualifier names.
* <p>
* 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.
*
* @return the qualifiers
* @return One or more qualifier name(s)
* @see #qualifiedBy()
* @see Named
*/
String[] qualifiedByName() default { };

28
core-common/src/main/java/org/mapstruct/MapMapping.java
View File

@ -66,11 +66,17 @@ public @interface MapMapping {
Class<? extends Annotation>[] keyQualifiedBy() default { };
/**
* See: { @link #keyQualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
* is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
* is no need to define own annotations.
* String-based form of qualifiers; When looking for a suitable mapping method to map this map mapping method's key
* type, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the class-level) a
* {@link Named} annotation for each of the specified qualifier names.
* <p>
* 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.
*
* @return the qualifiers
* @return One or more qualifier name(s)
* @see #keyQualifiedBy()
* @see Named
*/
String[] keyQualifiedByName() default { };
@ -87,11 +93,17 @@ public @interface MapMapping {
Class<? extends Annotation>[] valueQualifiedBy() default { };
/**
* See: { @link #valueQualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
* is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
* is no need to define own annotations.
* String-based form of qualifiers; When looking for a suitable mapping method to map this map mapping method's value
* type, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the class-level) a
* {@link Named} annotation for each of the specified qualifier names.
* <p>
* 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.
*
* @return the qualifiers
* @return One or more qualifier name(s)
* @see #valueQualifiedBy()
* @see Named
*/
String[] valueQualifiedByName() default { };

65
core-common/src/main/java/org/mapstruct/Named.java
View File

@ -24,19 +24,14 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* String-based qualifier.
*
* Marks mapping methods with the given qualifier name. Can be used to qualify a single method or all methods of a given
* type by specifying this annotation on the type level.
* <p>
* For more info see:
* <ul>
* <li>{@link Mapping#qualifiedByName() }</li>
* <li>{@link IterableMapping#qualifiedByName() }</li>
* <li>{@link MapMapping#keyQualifiedByName() }</li>
* <li>{@link MapMapping#valueQualifiedByName() }</li>
* </ul>
*
* Will be used to to select the correct mapping methods when mapping a bean property type, element of an iterable type
* or the key/value of a map type.
* <p>
* Example:
* Example (both methods of {@code Titles} are capable to convert a string, but the ambiguity is resolved by applying
* the qualifiers in {@code @Mapping}:
*
* <pre>
* <code>
@ -61,36 +56,46 @@ import java.lang.annotation.Target;
* GermanRelease toGerman( OriginalRelease movies );
*
* }
*
* Will generate:
*
* private final Titles titles = new Titles();
*
* &#64;Override
* public GermanRelease toGerman(OriginalRelease movies) {
* if ( movies == null ) {
* return null;
* }
*
* GermanRelease germanRelease = new GermanRelease();
*
* germanRelease.setTitle( titles.translateTitleEG( movies.getTitle() ) );
*
* return germanRelease;
* }
* </code>
* </pre>
*
* The following implementation of {@code MovieMapper} will be generated:
*
* <pre>
* <code>
*
* public class MovieMapperImpl implements MovieMapper {
* private final Titles titles = new Titles();
*
* &#64;Override
* public GermanRelease toGerman(OriginalRelease movies) {
* if ( movies == null ) {
* return null;
* }
*
* GermanRelease germanRelease = new GermanRelease();
*
* germanRelease.setTitle( titles.translateTitleEG( movies.getTitle() ) );
*
* return germanRelease;
* }
* }
* </code>
* </pre>
*
* @author Sjaak Derksen
* @see org.mapstruct.Mapping#qualifiedByName()
* @see IterableMapping#qualifiedByName()
* @see MapMapping#keyQualifiedByName()
* @see MapMapping#valueQualifiedByName()
*/
@Target( { ElementType.TYPE, ElementType.METHOD } )
@Retention( RetentionPolicy.RUNTIME )
@Qualifier
public @interface Named {
/**
*
* @return the name
* A name qualifying the annotated element
*/
String value();
}

14
core-jdk8/src/main/java/org/mapstruct/Mapping.java
View File

@ -138,11 +138,17 @@ public @interface Mapping {
Class<? extends Annotation>[] qualifiedBy() default { };
/**
* See: { @link #qualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
* is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
* is no need to define own annotations.
* 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 {@link Named} annotation
* for each of the specified qualifier names.
* <p>
* 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.
*
* @return the qualifiers
* @return One or more qualifier name(s)
* @see #qualifiedBy()
* @see Named
*/
String[] qualifiedByName() default { };

14
core/src/main/java/org/mapstruct/Mapping.java
View File

@ -136,11 +136,17 @@ public @interface Mapping {
Class<? extends Annotation>[] qualifiedBy() default { };
/**
* See: { @link #qualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
* is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
* is no need to define own annotations.
* 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 {@link Named} annotation
* for each of the specified qualifier names.
* <p>
* 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.
*
* @return the qualifiers
* @return One or more qualifier name(s)
* @see #qualifiedBy()
* @see Named
*/
String[] qualifiedByName() default { };