1 /*
2 * Copyright 2018 Andrew Rucker Jones.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.opencsv.bean;
17
18 import com.opencsv.exceptions.CsvRequiredFieldEmptyException;
19
20 import java.util.Collection;
21 import java.util.Locale;
22
23 /**
24 * Defines the basic characteristics of a map between field identifiers and
25 * their associated {@link BeanField}s.
26 * Such a mapping requires a method of matching multiple fields. This method
27 * will require data to initialize itself. Such a mapping also requires a key to
28 * index the {@link BeanField} that is to be provided for a match.
29 *
30 * @param <I> The initializer type used to build the many-to-one mapping
31 * @param <K> Type of the field identifier (key)
32 * @param <C> Type of the ComplexFieldMapEntry used. This is specified as a
33 * parameter so we can provide type safety and polymorphism through a generic
34 * interface on the one hand, and still extend specific implementations with
35 * methods needed for that type of complex mapping without having to add every
36 * such method to the generic interface.
37 * @param <T> The type of the bean
38 * @author Andrew Rucker Jones
39 * @since 4.2
40 */
41 public interface FieldMap<I, K extends Comparable<K>, C extends ComplexFieldMapEntry<I, K, T>, T> {
42
43 /**
44 * This method generates a header that can be used for writing beans of the
45 * type provided back to a file.
46 * Whether or not this generated header is used is decided by the
47 * {@link com.opencsv.bean.MappingStrategy} in use. The ordering of the
48 * headers should be carefully considered by the implementing class.
49 *
50 * @param bean One perfect, shining example of how the bean to be written
51 * should look. The most crucial thing is, for fields that result from
52 * joining multiple fields on reading and thus need to be split on
53 * writing, the {@link org.apache.commons.collections4.MultiValuedMap} in
54 * question must have the complete structure of the header to be
55 * generated, even if some values are empty.
56 * @return An array of header names for the output file
57 * @throws CsvRequiredFieldEmptyException If a required header is missing
58 * while attempting to write. Since every other header is hard-wired
59 * through the bean fields and their associated annotations, this can only
60 * happen with multi-valued fields.
61 */
62 String[] generateHeader(T bean) throws CsvRequiredFieldEmptyException;
63
64 /**
65 * Gets the {@link BeanField} associated with this key.
66 * If a key could possibly match both a regular, simple key (one added with
67 * {@link #put(Comparable, BeanField)}), and a
68 * complex key (one added with
69 * {@link #putComplex(java.lang.Object, com.opencsv.bean.BeanField)}), the
70 * simple key is always matched. If a key could match more than one complex
71 * key, the return value is undefined.
72 *
73 * @param key The key under which to search for a {@link BeanField}
74 * @return The {@link BeanField} found, or null if none is present
75 */
76 BeanField<T, K> get(K key);
77
78 /**
79 * Associates the given {@link BeanField} with the given {@code key}.
80 *
81 * @param key The key under which to index the provided {@link BeanField}
82 * @param value The {@link BeanField} to be indexed
83 * @return If there was a value previously associated with this key, it is
84 * returned
85 */
86 BeanField<T, K> put(K key, BeanField<T, K> value);
87
88 /**
89 * Adds a {@link BeanField} to this map indexed by the data in
90 * {@code initializer}.
91 * This is what makes this map special: It allows one to define
92 * characteristics of a method to match multiple keys.
93 *
94 * @param initializer Whatever data the implementation needs to match
95 * multiple keys
96 * @param value The {@link BeanField} that is to be returned on a later
97 * match
98 */
99 void putComplex(I initializer, BeanField<T, K> value);
100
101 /**
102 * Sets the locale to be used for error messages.
103 *
104 * @param errorLocale The locale to be used for error messages
105 */
106 void setErrorLocale(Locale errorLocale);
107
108 /**
109 * Provides all values currently in the map.
110 *
111 * @return The values in the map
112 */
113 Collection<BeanField<T, K>> values();
114
115 }