+ * 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 { }; diff --git a/core-common/src/main/java/org/mapstruct/MapMapping.java b/core-common/src/main/java/org/mapstruct/MapMapping.java index 0e1aa1a02..8b82991c4 100644 --- a/core-common/src/main/java/org/mapstruct/MapMapping.java +++ b/core-common/src/main/java/org/mapstruct/MapMapping.java @@ -66,11 +66,17 @@ public @interface MapMapping { Class[] 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. + *
+ * 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[] 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. + *
+ * 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 { }; diff --git a/core-common/src/main/java/org/mapstruct/Named.java b/core-common/src/main/java/org/mapstruct/Named.java index e0c6c567e..dd64aff5c 100644 --- a/core-common/src/main/java/org/mapstruct/Named.java +++ b/core-common/src/main/java/org/mapstruct/Named.java @@ -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. *
- * For more info see: - *
- * 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}: * *
*
@@ -61,36 +56,46 @@ import java.lang.annotation.Target;
* GermanRelease toGerman( OriginalRelease movies );
*
* }
- *
- * Will generate:
- *
- * private final Titles titles = new Titles();
- *
- * @Override
- * public GermanRelease toGerman(OriginalRelease movies) {
- * if ( movies == null ) {
- * return null;
- * }
- *
- * GermanRelease germanRelease = new GermanRelease();
- *
- * germanRelease.setTitle( titles.translateTitleEG( movies.getTitle() ) );
- *
- * return germanRelease;
- * }
*
*
*
+ * The following implementation of {@code MovieMapper} will be generated:
+ *
+ *
+ *
+ *
+ * public class MovieMapperImpl implements MovieMapper {
+ * private final Titles titles = new Titles();
+ *
+ * @Override
+ * public GermanRelease toGerman(OriginalRelease movies) {
+ * if ( movies == null ) {
+ * return null;
+ * }
+ *
+ * GermanRelease germanRelease = new GermanRelease();
+ *
+ * germanRelease.setTitle( titles.translateTitleEG( movies.getTitle() ) );
+ *
+ * return germanRelease;
+ * }
+ * }
+ *
+ *
*
* @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();
}
diff --git a/core-jdk8/src/main/java/org/mapstruct/Mapping.java b/core-jdk8/src/main/java/org/mapstruct/Mapping.java
index 4de5b553a..43dbbb7d9 100644
--- a/core-jdk8/src/main/java/org/mapstruct/Mapping.java
+++ b/core-jdk8/src/main/java/org/mapstruct/Mapping.java
@@ -138,11 +138,17 @@ public @interface Mapping {
Class[] 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.
+ * + * 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 { }; diff --git a/core/src/main/java/org/mapstruct/Mapping.java b/core/src/main/java/org/mapstruct/Mapping.java index 1c5f73a49..022cc143f 100644 --- a/core/src/main/java/org/mapstruct/Mapping.java +++ b/core/src/main/java/org/mapstruct/Mapping.java @@ -136,11 +136,17 @@ public @interface Mapping { Class[] 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. + *
+ * 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 { };