mapstruct · filiphr · Aug 20, 2022 · Mar 7, 2022 · Mar 8, 2022 · Mar 9, 2022
diff --git a/core/src/main/java/org/mapstruct/AnnotateWith.java b/core/src/main/java/org/mapstruct/AnnotateWith.java
@@ -0,0 +1,176 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Annotation;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.CLASS;
+
+/**
+ * This can be used to have mapstruct generate additional annotations on classes/methods.
+ * <p>
+ * Examples based on the spring framework annotations.
+ * </p>
+ * Marking a class as `Lazy`:
+ *
+ * <pre><code>
+ * &#64;AnnotateWith( value = Lazy.class )
+ * &#64;Mapper
+ * public interface FooMapper {
+ *     // mapper code
+ * }
+ * </code></pre>
+ *
+ * The following code would be generated:
+ *
+ * <pre><code>
+ * &#64;Lazy
+ * public class FooMapperImpl implements FooMapper {
+ *     // mapper code
+ * }
+ * </code></pre>
+ * Setting the profile on the generated implementation:
+ *
+ * <pre><code>
+ * &#64;AnnotateWith( value = Profile.class, elements = @AnnotateWith.Element( strings = "prod" ) )
+ * &#64;Mapper
+ * public interface FooMapper {
+ *     // mapper code
+ * }
+ * </code></pre>
+ *
+ * The following code would be generated:
+ *
+ * <pre><code>
+ * &#64;Profile( value = "prod" )
+ * public class FooMapperImpl implements FooMapper {
+ *     // mapper code
+ * }
+ * </code></pre>
+ *
+ * @author Ben Zegveld
+ * @since 1.6
+ */
+@Repeatable( AnnotateWiths.class )
+@Retention( CLASS )
+@Target( { TYPE, METHOD, ANNOTATION_TYPE } )
+public @interface AnnotateWith {
+    /**
+     * @return the annotation class that needs to be added.
+     */
+    Class<? extends Annotation> value();
+
+    /**
+     * @return the annotation elements that are to be applied to this annotation.
+     */
+    Element[] elements() default {};
+
+    /**
+     * Used in combination with {@link AnnotateWith} to configure the annotation elements. Only 1 value type may be used
+     * within the same annotation at a time. For example mixing shorts and ints is not allowed.
+     *
+     * @author Ben Zegveld
+     * @since 1.6
+     */
+    @interface Element {
+        /**
+         * @return name of the annotation element.
+         */
+        String name() default "value";
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return short value(s) for the annotation element.
+         */
+        short[] shorts() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return byte value(s) for the annotation element.
+         */
+        byte[] bytes() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return int value(s) for the annotation element.
+         */
+        int[] ints() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return long value(s) for the annotation element.
+         */
+        long[] longs() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return float value(s) for the annotation element.
+         */
+        float[] floats() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return double value(s) for the annotation element.
+         */
+        double[] doubles() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return char value(s) for the annotation element.
+         */
+        char[] chars() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return boolean value(s) for the annotation element.
+         */
+        boolean[] booleans() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return string value(s) for the annotation element.
+         */
+        String[] strings() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return class value(s) for the annotation element.
+         */
+        Class<?>[] classes() default {};
+
+        /**
+         * only used in conjunction with the {@link #enums()} annotation element.
+         *
+         * @return the class of the enum.
+         */
+        Class<? extends Enum<?>> enumClass() default NullEnum.class;
+
+        /**
+         * cannot be used in conjunction with other value fields. {@link #enumClass()} is also required when using
+         * {@link #enums()}
+         *
+         * @return enum value(s) for the annotation element.
+         */
+        String[] enums() default {};
+
+    }
+}
diff --git a/core/src/main/java/org/mapstruct/AnnotateWiths.java b/core/src/main/java/org/mapstruct/AnnotateWiths.java
@@ -0,0 +1,31 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.CLASS;
+
+/**
+ * This can be used to have mapstruct generate additional annotations on classes/methods.
+ *
+ * @author Ben Zegveld
+ * @since 1.6
+ */
+@Retention( CLASS )
+@Target( { TYPE, METHOD } )
+public @interface AnnotateWiths {
+
+    /**
+     * The configuration of the additional annotations.
+     *
+     * @return The configuration of the additional annotations.
+     */
+    AnnotateWith[] value();
+}
diff --git a/core/src/main/java/org/mapstruct/NullEnum.java b/core/src/main/java/org/mapstruct/NullEnum.java
@@ -0,0 +1,15 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * To be used as a default value for enum class annotation elements.
+ *
+ * @author Ben Zegveld
+ * @since 1.6
+ */
+enum NullEnum {
+}
diff --git a/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc b/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc
@@ -720,3 +720,43 @@ i.e. You can map from `Map<String, Integer>` where for each property a conversio
 When a raw map or a map that does not have a String as a key is used, then a warning will be generated.
 The warning is not generated if the map itself is mapped into some other target property directly as is.
 ====
+
+[[adding-annotations]]
+=== Adding annotations
+
+Other frameworks sometimes requires you to add annotations to certain classes so that they can easily detect the mappers.
+Using the `@AnnotateWith` annotation you can generate an annotation at the specified location.
+
+For example Apache Camel has a `@Converter` annotation which you can apply to generated mappers using the `@AnnotateWith` annotation.
+
+.AnnotateWith source example
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+@Mapper
+@AnnotateWith(
+  value = Converter.class,
+  elements = @AnnotateWith.Element( name = "generateBulkLoader", booleans = true )
+)
+public interface MyConverter {
+    @AnnotateWith( Converter.class )
+    DomainObject map( DtoObject dto );
+}
+----
+====
+
+.AnnotateWith generated mapper
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+@Converter( generateBulkLoader = true )
+public class MyConverterImpl implements MyConverter {
+    @Converter
+    public DomainObject map( DtoObject dto ) {
+        // default mapping behaviour
+    }
+}
+----
+====
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/gem/GemGenerator.java b/processor/src/main/java/org/mapstruct/ap/internal/gem/GemGenerator.java
@@ -9,6 +9,8 @@
 import javax.xml.bind.annotation.XmlElementRef;
 
 import org.mapstruct.AfterMapping;
+import org.mapstruct.AnnotateWith;
+import org.mapstruct.AnnotateWiths;
 import org.mapstruct.BeanMapping;
 import org.mapstruct.BeforeMapping;
 import org.mapstruct.Builder;
@@ -42,6 +44,9 @@
  *
  * @author Gunnar Morling
  */
+@GemDefinition(AnnotateWith.class)
+@GemDefinition(AnnotateWith.Element.class)
+@GemDefinition(AnnotateWiths.class)
 @GemDefinition(Mapper.class)
 @GemDefinition(Mapping.class)
 @GemDefinition(Mappings.class)