001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall.csv;
018
019import static org.apache.juneau.commons.utils.Shorts.*;
020
021import java.io.*;
022import java.util.*;
023import java.util.concurrent.*;
024
025import org.apache.juneau.commons.bean.*;
026import org.apache.juneau.commons.collections.*;
027import org.apache.juneau.marshall.*;
028import org.apache.juneau.marshall.serializer.*;
029import org.apache.juneau.marshall.stream.*;
030
031/**
032 * Serializes POJO models to CSV (Comma Separated Values) format.
033 *
034 * <p>
035 * This serializer converts Java objects (primarily collections of beans) into CSV format, where each bean
036 * becomes a row and bean properties become columns. The first row typically contains column headers derived
037 * from bean property names.
038 *
039 * <h2 class='section'>JSON Parity Features (opt-in):</h2>
040 * <ul>
041 *   <li><b>Type discriminator</b> — {@link CsvSerializer.Builder#addBeanTypes() addBeanTypes()}.{@link CsvSerializer.Builder#addRootType() addRootType()}
042 *       adds a {@code _type} column for polymorphic parsing.
043 *   <li><b>Byte arrays</b> — {@link CsvSerializer.Builder#byteArrayFormat(CsvByteArrayCellFormat) byteArrayFormat(BASE64)} (default) or
044 *       {@code SEMICOLON_DELIMITED} for {@code byte[]}; primitive arrays as {@code [1;2;3]}.
045 *   <li><b>Nested structures</b> — {@link CsvSerializer.Builder#allowNestedStructures(boolean) allowNestedStructures(true)}
046 *       enables inline {@code {key:val}} and {@code [val;val]} in cells.
047 *   <li><b>Null marker</b> — {@link CsvSerializer.Builder#nullValue(String) nullValue("&lt;NULL&gt;")} (default) for unambiguous null.
048 * </ul>
049 *
050 * <h2 class='section'>Data Structures Not Supported:</h2>
051 * <ul>
052 *   <li><b>Parent/inherited properties</b> — Hierarchy flattens; may collide with child names.
053 *   <li><b>Optional wrappers</b> — May serialize as the inner value; round-trip differs from tree formats.
054 * </ul>
055 *
056 * <h2 class='section'>Best Supported:</h2>
057 * <p>
058 * Collections of flat beans or maps whose properties are primitives, strings, numbers, enums, dates,
059 * byte arrays, or (with {@code allowNestedStructures}) nested beans, maps, and lists.
060 *
061 * <h2 class='figure'>Example output (list of maps with a,b):</h2>
062 * <p class='bcode'>
063 *    a,b
064 *    foo,bar
065 * </p>
066 *
067 * <h2 class='figure'>Complex (list of beans with nested address, flattened):</h2>
068 * <p class='bcode'>
069 *    name,age,address_street,address_city,address_state,tags
070 *    Alice,30,123 Main St,Boston,MA,"a,b,c"
071 * </p>
072 *
073 * <h2 class='section'>Notes:</h2><ul>
074 *    <li class='note'>This class is thread safe and reusable.
075 * </ul>
076 *
077 */
078@SuppressWarnings({
079   "java:S110", // Inheritance depth acceptable for this class hierarchy
080   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
081   "java:S9149", // Per-format static factories intentionally shadow the parent's.
082   "resource" // Closeable resources are owned by the caller's serializer session; Eclipse JDT @Owning warning is by design.
083})
084public class CsvSerializer extends WriterSerializer implements CsvMetaProvider, RecordWritable {
085
086   /**
087    * Builder class.
088    */
089   public static class Builder extends WriterSerializer.Builder<Builder> {
090
091      private static final Cache<HashKey,CsvSerializer> CACHE = Cache.of(HashKey.class, CsvSerializer.class).build();
092
093      private CsvByteArrayCellFormat byteArrayFormat;
094      private boolean allowNestedStructures;
095      private boolean neutralizeFormulas;
096      private String nullValue;
097
098      /**
099       * Constructor, default settings.
100       */
101      protected Builder() {
102         produces("text/csv");
103         byteArrayFormat = CsvByteArrayCellFormat.BASE64;
104         nullValue = "<NULL>";
105      }
106
107      /**
108       * Copy constructor.
109       *
110       * @param copyFrom The builder to copy from.
111       *    <br>Cannot be <jk>null</jk>.
112       */
113      protected Builder(Builder copyFrom) {
114         super(reqnn("copyFrom", copyFrom));
115         byteArrayFormat = copyFrom.byteArrayFormat;
116         allowNestedStructures = copyFrom.allowNestedStructures;
117         neutralizeFormulas = copyFrom.neutralizeFormulas;
118         nullValue = copyFrom.nullValue;
119      }
120
121      /**
122       * Copy constructor.
123       *
124       * @param copyFrom The bean to copy from.
125       *    <br>Cannot be <jk>null</jk>.
126       */
127      protected Builder(CsvSerializer copyFrom) {
128         super(reqnn("copyFrom", copyFrom));
129         byteArrayFormat = copyFrom.byteArrayFormat;
130         allowNestedStructures = copyFrom.allowNestedStructures;
131         neutralizeFormulas = copyFrom.neutralizeFormulas;
132         nullValue = copyFrom.nullValue;
133      }
134
135      /**
136       * String to write for null values. Parser treats cells matching this as null.
137       *
138       * <p>
139       * Default is {@code <NULL>} to avoid confusion with the literal string {@code "null"}.
140       *
141       * @param value The null marker string.
142       * @return This object.
143       */
144      public Builder nullValue(String value) {
145         nullValue = value;
146         return this;
147      }
148
149      /**
150       * Enables inline {@code {key:val}} and {@code [val;val]} notation in cells for nested beans, maps, and lists.
151       *
152       * @param value Whether to allow nested structures.
153       * @return This object.
154       */
155      public Builder allowNestedStructures(boolean value) {
156         allowNestedStructures = value;
157         return this;
158      }
159
160      /**
161       * Neutralizes spreadsheet formulas in string cells.
162       *
163       * <p>
164       * When enabled, string cells (and header names) that begin with <js>'='</js>, <js>'+'</js>, <js>'-'</js>, <js>'@'</js>,
165       * a tab or a carriage return are prefixed with a single quote so that spreadsheet applications treat them as text.
166       * Numbers and other non-string values are not modified.
167       * Enable this when CSV output containing untrusted text will be opened in a spreadsheet.
168       * The default is <jk>false</jk>, so that values round-trip through {@link CsvParser} unchanged.
169       *
170       * @param value Whether to neutralize formulas.
171       * @return This object.
172       */
173      public Builder neutralizeFormulas(boolean value) {
174         neutralizeFormulas = value;
175         return this;
176      }
177
178      /**
179       * Format for serializing {@code byte[]} arrays in CSV cells.
180       *
181       * <p>
182       * Default is {@link CsvByteArrayCellFormat#BASE64} (matches JSON).
183       *
184       * @param value The format to use.
185       * @return This object.
186       */
187      public Builder byteArrayFormat(CsvByteArrayCellFormat value) {
188         byteArrayFormat = value;
189         return this;
190      }
191
192      @Override /* Overridden from Context.Builder<?> */
193      public HashKey hashKey() {
194         return HashKey.of(super.hashKey(), byteArrayFormat, allowNestedStructures, neutralizeFormulas, nullValue);
195      }
196
197      @Override /* Overridden from Context.Builder<?> */
198      public CsvSerializer build() {
199         return cache(CACHE).build(CsvSerializer.class);
200      }
201
202      @Override /* Overridden from Context.Builder<?> */
203      public Builder copy() {
204         return new Builder(this);
205      }
206
207
208   }
209
210   /** Default serializer, all default settings.*/
211   public static final CsvSerializer DEFAULT = new CsvSerializer(create());
212
213   /**
214    * Creates a new builder for this object.
215    *
216    * @return A new builder.
217    */
218   public static Builder create() {
219      return new Builder();
220   }
221
222   private final Map<ClassMeta<?>,CsvClassMeta> csvClassMetas = new ConcurrentHashMap<>();
223   private final Map<BeanPropertyMeta,CsvBeanPropertyMeta> csvBeanPropertyMetas = new ConcurrentHashMap<>();
224   private final CsvByteArrayCellFormat byteArrayFormat;
225   private final boolean allowNestedStructures;
226   private final boolean neutralizeFormulas;
227   private final String nullValue;
228
229   /**
230    * Constructor.
231    *
232    * @param builder The builder for this object.
233    */
234   public CsvSerializer(Builder builder) {
235      super(builder);
236      byteArrayFormat = or(builder.byteArrayFormat, CsvByteArrayCellFormat.BASE64);
237      allowNestedStructures = builder.allowNestedStructures;
238      neutralizeFormulas = builder.neutralizeFormulas;
239      nullValue = or(builder.nullValue, "<NULL>");
240   }
241
242   /**
243    * Returns the format for serializing {@code byte[]} arrays in CSV cells.
244    *
245    * @return The byte array format.
246    */
247   public CsvByteArrayCellFormat getByteArrayFormat() {
248      return byteArrayFormat;
249   }
250
251   /**
252    * Returns whether inline {@code {key:val}} and {@code [val;val]} notation is enabled.
253    *
254    * @return Whether nested structures are allowed.
255    */
256   public boolean isAllowNestedStructures() {
257      return allowNestedStructures;
258   }
259
260   /**
261    * Returns whether spreadsheet formulas in string cells are neutralized.
262    *
263    * @return Whether formulas are neutralized.
264    */
265   public boolean isNeutralizeFormulas() {
266      return neutralizeFormulas;
267   }
268
269   /**
270    * Returns the string written for null values.
271    *
272    * @return The null marker.
273    */
274   public String getNullValue() {
275      return nullValue;
276   }
277
278   @Override /* Overridden from Context */
279   public Builder copy() {
280      return new Builder(this);
281   }
282
283   @Override /* Overridden from Context */
284   public CsvSerializerSession.Builder createSession() {
285      return CsvSerializerSession.create(this);
286   }
287
288   @Override /* Overridden from CsvMetaProvider */
289   public CsvBeanPropertyMeta getCsvBeanPropertyMeta(BeanPropertyMeta bpm) {
290      if (bpm == null)
291         return CsvBeanPropertyMeta.DEFAULT;
292      return csvBeanPropertyMetas.computeIfAbsent(bpm, k -> new CsvBeanPropertyMeta(k.getDelegateFor(), this));
293   }
294
295   @Override /* Overridden from CsvMetaProvider */
296   public CsvClassMeta getCsvClassMeta(ClassMeta<?> cm) {
297      return csvClassMetas.computeIfAbsent(cm, k -> new CsvClassMeta(k, this));
298   }
299
300   @Override /* Overridden from Context */
301   public CsvSerializerSession getSession() { return createSession().build(); }
302
303   /**
304    * Convenience delegator that opens a {@link RecordWriter} over the output using
305    * <b>default session arguments</b> (mirrors {@link #write(Object)}).
306    *
307    * <p>
308    * CSV is naturally row-oriented &mdash; each {@link RecordWriter#write(Object) write(...)} call appends
309    * one row &mdash; but the current cursor is buffered (the full list is materialized at close); a streaming
310    * implementation is a Phase 3b deferred item, so {@link #isRecordStreaming()} returns <jk>false</jk>.
311    *
312    * <p>
313    * The real implementation lives on {@link CsvSerializerSession#writeRecords(Object)}.  Callers that
314    * need request-derived configuration should call {@link #createSession()} and invoke
315    * {@link CsvSerializerSession#writeRecords(Object)} on the built session instead.
316    *
317    * @param output The output.
318    * @return A new {@link RecordWriter}.
319    * @throws IOException If a problem occurred opening the underlying output.
320    */
321   @Override /* RecordWritable */
322   public RecordWriter writeRecords(Object output) throws IOException {
323      return getSession().writeRecords(output);
324   }
325
326   @Override /* RecordWritable */
327   public boolean isRecordStreaming() {
328      return false;
329   }
330}