1 package io.oasp.module.beanmapping.common.api;
2
3 import java.util.List;
4 import java.util.Set;
5
6 /**
7 * This is the interface used to convert from one Java bean to another compatible bean (e.g. from a JPA entity to a
8 * corresponding transfer-object).
9 *
10 * @author hohwille
11 */
12 public interface BeanMapper {
13
14 /**
15 * Recursively converts the given <code>source</code> {@link Object} to the given target {@link Class}.
16 *
17 * @param <T> is the generic type to convert to.
18 * @param source is the object to convert.
19 * @param targetClass is the {@link Class} reflecting the type to convert to.
20 * @return the converted object. Will be {@code null} if <code>source</code> is {@code null}.
21 */
22 <T> T map(Object source, Class<T> targetClass);
23
24 /**
25 * A type-safe variant of {@link #map(Object, Class)} to prevent accidental abuse (e.g. mapping of apples to bananas).
26 *
27 * @param <API> is a common super-type (interface) of <code>source</code> and <code>targetType</code>.
28 * @param <S> is the generic type of <code>source</code>.
29 * @param <T> is the generic type to convert to (target).
30 * @param apiClass is the {@link Class} reflecting the {@literal <API>}.
31 * @param source is the object to convert.
32 * @param targetClass is the {@link Class} reflecting the type to convert to.
33 * @return the converted object. Will be {@code null} if <code>source</code> is {@code null}.
34 * @since 1.3.0
35 */
36 <API, S extends API, T extends API> T mapTypesafe(Class<API> apiClass, S source, Class<T> targetClass);
37
38 /**
39 * Creates a new {@link List} with the {@link #map(Object, Class) mapped bean} for each {@link List#get(int) entry} of
40 * the given {@link List}. Uses {@code false} for <code>suppressNullValues</code> (see
41 * {@link #mapList(List, Class, boolean)}).
42 *
43 * @param <T> is the generic type to convert the {@link List} entries to.
44 * @param source is the {@link List} with the source objects.
45 * @param targetClass is the {@link Class} reflecting the type to convert each {@link List} entry to.
46 * @return the {@link List} with the converted objects. Will be {@link List#isEmpty() empty} is <code>source</code> is
47 * empty or {@code null}.
48 */
49 <T> List<T> mapList(List<?> source, Class<T> targetClass);
50
51 /**
52 * Creates a new {@link List} with the {@link #map(Object, Class) mapped bean} for each {@link List#get(int) entry} of
53 * the given {@link List}.
54 *
55 * @param <T> is the generic type to convert the {@link List} entries to.
56 * @param source is the {@link List} with the source objects.
57 * @param targetClass is the {@link Class} reflecting the type to convert each {@link List} entry to.
58 * @param suppressNullValues {@code true} if {@code null} values shall be suppressed/omitted in the
59 * resulting {@link List}, {@code false} otherwise.
60 * @return the {@link List} with the converted objects. Will be {@link List#isEmpty() empty} is <code>source</code> is
61 * empty or {@code null}.
62 * @since 1.3.0
63 */
64 <T> List<T> mapList(List<?> source, Class<T> targetClass, boolean suppressNullValues);
65
66 /**
67 * Creates a new {@link Set} with the {@link #map(Object, Class) mapped bean} for each {@link Set#contains(Object)
68 * entry} of the given {@link Set}. Uses {@code false} for <code>suppressNullValues</code> (see
69 * {@link #mapSet(Set, Class, boolean)}).
70 *
71 * @param <T> is the generic type to convert the {@link Set} entries to.
72 * @param source is the {@link Set} with the source objects.
73 * @param targetClass is the {@link Class} reflecting the type to convert each {@link Set} entry to.
74 * @return the {@link Set} with the converted objects. Will be {@link Set#isEmpty() empty} is <code>source</code> is
75 * empty or {@code null}.
76 */
77 <T> Set<T> mapSet(Set<?> source, Class<T> targetClass);
78
79 /**
80 * Creates a new {@link Set} with the {@link #map(Object, Class) mapped bean} for each {@link Set#contains(Object)
81 * entry} of the given {@link Set}.
82 *
83 * @param <T> is the generic type to convert the {@link Set} entries to.
84 * @param source is the {@link Set} with the source objects.
85 * @param targetClass is the {@link Class} reflecting the type to convert each {@link Set} entry to.
86 * @param suppressNullValues {@code true} if {@code null} values shall be suppressed/omitted in the
87 * resulting {@link Set}, {@code false} otherwise.
88 * @return the {@link Set} with the converted objects. Will be {@link Set#isEmpty() empty} is <code>source</code> is
89 * empty or {@code null}.
90 * @since 1.3.0
91 */
92 <T> Set<T> mapSet(Set<?> source, Class<T> targetClass, boolean suppressNullValues);
93
94 }