org.mapstruct.IterableMapping Maven / Gradle / Ivy
Show all versions of mapstruct-jdk8 Show documentation
/**
* Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
* and/or other contributors as indicated by the @authors tag. See the
* copyright.txt file in the distribution for a full listing of all
* contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.mapstruct;
import java.lang.annotation.Annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.text.SimpleDateFormat;
import java.text.DecimalFormat;
import java.util.Date;
/**
* Configures the mapping between two iterable like types, e.g. {@code List} and {@code List}.
*
*
* Note: either @IterableMapping#dateFormat, @IterableMapping#resultType or @IterableMapping#qualifiedBy
* must be specified
*
* Supported mappings are:
*
* - {@code Iterable} to/from {@code Iterable}/{@code Iterable}
* - {@code Iterable} to/from {@code B[]}/{@code A[]}
* - {@code Iterable} to/from {@code Stream}/{@code Stream}
* - {@code A[]} to/from {@code Stream}/{@code Stream}
* - {@code A[]} to/from {@code B[]}
* - {@code Stream} to/from {@code Stream}
*
*
* @author Gunnar Morling
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
public @interface IterableMapping {
/**
* A format string as processable by {@link SimpleDateFormat} if the annotated method maps from an iterable of
* {@code String} to an iterable {@link Date} or vice-versa. Will be ignored for all other element types.
*
* @return A date format string as processable by {@link SimpleDateFormat}.
*/
String dateFormat() default "";
/**
* A format string as processable by {@link DecimalFormat} if the annotated method maps from a
* {@link Number} to a {@link String} or vice-versa. Will be ignored for all other element types.
*
* @return A decimal format string as processable by {@link DecimalFormat}.
*/
String numberFormat() default "";
/**
* A qualifier can be specified to aid the selection process of a suitable mapper. This is useful in case multiple
* mappers (hand written of internal) qualify and result in an 'Ambiguous mapping methods found' error.
*
* A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
*
* @return the qualifiers
*/
Class[] qualifiedBy() default { };
/**
* 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.
*
* 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 One or more qualifier name(s)
* @see #qualifiedBy()
* @see Named
*/
String[] qualifiedByName() default { };
/**
* Specifies the type of the element to be used in the result of the mapping method in case multiple mapping
* methods qualify.
*
* @return the elementTargetType to select
*/
Class elementTargetType() default void.class;
/**
* The strategy to be applied when {@code null} is passed as source value to this iterable mapping. If no
* strategy is configured, the strategy given via {@link MapperConfig#nullValueMappingStrategy()} or
* {@link Mapper#nullValueMappingStrategy()} will be applied, using {@link NullValueMappingStrategy#RETURN_NULL}
* by default.
*
* @return The strategy to be applied when {@code null} is passed as source value to the methods of this mapping.
*/
NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
}