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.CollectionUtils.*;
020import static org.apache.juneau.commons.utils.Shorts.*;
021import static org.apache.juneau.commons.utils.StringUtils.*;
022
023import java.io.*;
024import java.time.*;
025import java.time.Duration;
026import java.time.temporal.*;
027import java.util.*;
028
029import javax.xml.datatype.*;
030
031import org.apache.juneau.commons.bean.*;
032import org.apache.juneau.commons.lang.*;
033import org.apache.juneau.marshall.*;
034import org.apache.juneau.marshall.serializer.*;
035import org.apache.juneau.marshall.stream.*;
036import org.apache.juneau.marshall.swap.spi.*;
037
038/**
039 * Session object that lives for the duration of a single use of {@link CsvSerializer}.
040 *
041 * <h2 class='section'>Notes:</h2><ul>
042 *    <li class='warn'>This class is not thread safe and is typically discarded after one use.
043 * </ul>
044 *
045 */
046@SuppressWarnings({
047   "java:S110", // Inheritance depth acceptable for serializer session hierarchy
048   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
049   "java:S3776", // Cognitive complexity acceptable for doWrite, formatForCsvCell
050   "java:S6541", // Brain method acceptable for doWrite, formatForCsvCell
051   "rawtypes", // doWrite() casts the first entry and swapped values to a raw Map after instanceof/ClassMeta checks
052   "resource" // Internal helpers return Closeables wired into pipe lifecycle; Eclipse JDT @Owning warning is by design.
053})
054public class CsvSerializerSession extends WriterSerializerSession implements RecordWritable {
055
056   private final CsvByteArrayCellFormat byteArrayFormat;
057   private final boolean allowNestedStructures;
058   private final boolean neutralizeFormulas;
059   private final String nullValue;
060
061   /**
062    * Builder class.
063    */
064   public static class Builder extends WriterSerializerSession.Builder<Builder> {
065
066      private CsvByteArrayCellFormat byteArrayFormat;
067      private boolean allowNestedStructures;
068      private boolean neutralizeFormulas;
069      private String nullValue;
070
071      /**
072       * Constructor
073       *
074       * @param ctx The context creating this session.
075       *    <br>Cannot be <jk>null</jk>.
076       */
077      protected Builder(CsvSerializer ctx) {
078         super(reqnn("ctx", ctx));
079         byteArrayFormat = ctx.getByteArrayFormat();
080         allowNestedStructures = ctx.isAllowNestedStructures();
081         neutralizeFormulas = ctx.isNeutralizeFormulas();
082         nullValue = ctx.getNullValue();
083      }
084
085      /**
086       * Allow nested structures.
087       *
088       * @param value The new value for this property.
089       * @return This object.
090       */
091      public Builder allowNestedStructures(boolean value) {
092         allowNestedStructures = value;
093         return this;
094      }
095
096      /**
097       * Neutralize spreadsheet formulas in string cells.
098       *
099       * @param value The new value for this property.
100       * @return This object.
101       */
102      public Builder neutralizeFormulas(boolean value) {
103         neutralizeFormulas = value;
104         return this;
105      }
106
107      @Override
108      public CsvSerializerSession build() {
109         return new CsvSerializerSession(this);
110      }
111
112      /**
113       * Byte array format.
114       *
115       * @param value The new value for this property.
116       * @return This object.
117       */
118      public Builder byteArrayFormat(CsvByteArrayCellFormat value) {
119         if (nn(value))
120            byteArrayFormat = value;
121         return this;
122      }
123
124      /**
125       * Null value string.
126       *
127       * @param value The new value for this property. Can be <jk>null</jk> (resets to default).
128       * @return This object.
129       */
130      public Builder nullValue(String value) {
131         nullValue = value;
132         return this;
133      }
134
135      @Override /* Overridden from Builder */
136      public Builder property(String key, Object value) {
137         if (key == null) {
138            super.property(key, value);
139            return this;
140         }
141         switch (key) {
142            case "byteArrayFormat", "CsvSerializerSession.byteArrayFormat":
143               return byteArrayFormat(cvt(value, CsvByteArrayCellFormat.class));
144            case "allowNestedStructures", "CsvSerializerSession.allowNestedStructures":
145               return allowNestedStructures(cvt(value, Boolean.class));
146            case "neutralizeFormulas", "CsvSerializerSession.neutralizeFormulas":
147               return neutralizeFormulas(cvt(value, Boolean.class));
148            case "nullValue", "CsvSerializerSession.nullValue":
149               return nullValue(cvt(value, String.class));
150            default:
151               super.property(key, value);
152               return this;
153         }
154      }
155
156   }
157
158   /**
159    * Creates a new builder for this object.
160    *
161    * @param ctx The context creating this session.
162    *    <br>Cannot be <jk>null</jk>.
163    * @return A new builder.
164    */
165   public static Builder create(CsvSerializer ctx) {
166      return new Builder(reqnn("ctx", ctx));
167   }
168
169   /**
170    * Constructor.
171    *
172    * @param builder The builder for this object.
173    */
174   protected CsvSerializerSession(Builder builder) {
175      super(builder);
176      byteArrayFormat = builder.byteArrayFormat;
177      allowNestedStructures = builder.allowNestedStructures;
178      neutralizeFormulas = builder.neutralizeFormulas;
179      nullValue = or(builder.nullValue, "<NULL>");
180   }
181
182   @Override /* RecordWritable */
183   public RecordWriter writeRecords(Object output) throws IOException {
184      return RecordAdapter.arrayWriter(this, output);
185   }
186
187   @Override /* RecordWritable */
188   public boolean isRecordStreaming() {
189      return false;
190   }
191
192   /**
193    * Applies any registered object swap to the specified value.
194    *
195    * <p>
196    * If a swap is registered for the value's type, the value is transformed using the swap's
197    * {@code swap()} method before being serialized.
198    *
199    * @param value The value to potentially swap.
200    * @param type The class metadata of the value's type.
201    * @return The swapped value, or the original value if no swap is registered.
202    */
203   private Object applySwap(Object value, ClassMeta<?> type) {
204      try {
205         if (value == null || type == null)
206            return value;
207
208         ObjectSwap swap = type.getSwap(this);
209         if (nn(swap)) {
210            return swap(swap, value);
211         }
212         if (type.isDate())
213            return writeDate((Date)value, type);
214         if (type.isCalendar())
215            return writeCalendar(value, type);
216         if (type.isTemporal())
217            return writeTemporal((TemporalAccessor)value, type);
218         if (type.isDuration())
219            return writeDuration((Duration)value);
220         if (type.isPeriod())
221            return writePeriod((Period)value);
222         return value;
223      } catch (SerializeException e) {
224         throw rex(e);
225      }
226   }
227
228   @SuppressWarnings({
229      "unchecked" // Type erasure requires unchecked casts
230   })
231   @Override /* Overridden from SerializerSession */
232   protected void doWrite(SerializerPipe pipe, Object o) throws IOException, SerializeException {
233      var cm = push2("root", o, getClassMetaForObject(o));
234      if (cm == null)
235         return;
236      try {
237         try (var w = getCsvWriter(pipe)) {
238            Collection<?> l = null;
239            if (cm.isArray()) {
240            // Primitive arrays and byte[] serialize as single row (value = [1;2;3] or base64)
241            if (o.getClass().getComponentType().isPrimitive())
242               l = Collections.singletonList(o);
243            else
244               l = l((Object[])o);
245         } else if (cm.isCollection()) {
246            l = (Collection<?>)o;
247         } else if (cm.isStreamable()) {
248            // CSV must inspect first element for column headers, so materialization is unavoidable.
249            l = toListFromStreamable(o, cm);
250         } else {
251            l = Collections.singleton(o);
252         }
253
254         if (ine(l)) {
255            var firstOpt = first(l);
256            if (!firstOpt.isPresent())
257               return;
258
259            // Apply any registered swap to the first element to determine column structure.
260            var firstRaw = firstOpt.get();
261            var firstEntry = applySwap(firstRaw, getClassMetaForObject(firstRaw));
262            var entryType = getClassMetaForObject(firstEntry);
263            // If swapped type is not a bean (e.g. interface proxy), use raw type for strategy
264            if (! entryType.isBean() && firstRaw != null) {
265               var rawType = getClassMetaForObject(firstRaw);
266               if (rawType.isBean())
267                  entryType = rawType;
268            }
269
270            // Expected type for each element (for type discriminator)
271            var eType = cm.isArray() || cm.isCollection() || cm.isStreamable()
272               ? cm.getElementType()
273               : getExpectedRootType(firstRaw);
274
275            // CSV is flat; when addBeanTypes or addRootType is set, add _type column to all rows
276            var addTypeColumn = isAddBeanTypes() || isAddRootType();
277            var typeColName = addTypeColumn ? getBeanTypePropertyName(entryType) : null;
278
279            // Determine the best representation strategy.
280            // Use the BeanMeta from the entry type for bean serialization.
281            var bm = entryType.isBean() ? entryType.getBeanMeta() : null;
282
283            if (bm != null) {
284               // Bean or DynaBean path: header row = property names + optional _type
285               var addComma = Flag.create();
286               bm.getProperties().values().stream().filter(BeanPropertyMeta::canRead).forEach(x -> {
287                  addComma.ifSet(() -> w.w(',')).set();
288                  w.writeEntry(x.getName());
289               });
290               // Always append _type when addBeanTypes or addRootType to support polymorphic parsing
291               if (addTypeColumn && ine(typeColName)) {
292                  w.w(',');
293                  w.writeEntry(typeColName);
294               }
295               w.append('\n');
296               var readableProps = bm.getProperties().values().stream().filter(BeanPropertyMeta::canRead).toList();
297               l.forEach(x -> {
298                  var addComma2 = Flag.create();
299                  if (x == null) {
300                     // Null entry: write null marker for each column
301                     readableProps.forEach(y -> {
302                        addComma2.ifSet(() -> w.w(',')).set();
303                        w.writeEntry(nullValue);
304                     });
305                     if (addTypeColumn && ine(typeColName)) {
306                        w.w(',');
307                        w.writeEntry("");
308                     }
309                  } else {
310                     // Apply swap before extracting bean properties (e.g. surrogate swaps)
311                     var swapped = applySwap(x, getClassMetaForObject(x));
312                     var aType = getClassMetaForObject(swapped);
313                     // When swap yields non-bean (e.g. String), use raw object for property extraction
314                     var objForBean = aType.isBean() ? swapped : x;
315                     BeanMap<?> bean = toBeanMap(objForBean);
316                     readableProps.forEach(y -> {
317                        addComma2.ifSet(() -> w.w(',')).set();
318                        var value = y.get(bean, y.getName());
319                        value = formatIfDateOrDuration(value);
320                        value = formatForCsvCell(value);
321                        // Use toString() to respect trimStrings setting on String values
322                        if (value instanceof String value2) value = toString(value2);
323                        w.writeEntry(or(value, nullValue));
324                     });
325                     if (addTypeColumn && ine(typeColName)) {
326                        var typeName = getBeanTypeName(this, eType, aType, null);
327                        w.w(',');
328                        w.writeEntry(or(typeName, ""));
329                     }
330                  }
331                  w.w('\n');
332               });
333            } else if (entryType.isMap()) {
334               // Map path: header row = map keys from the first entry + optional _type
335               var addComma = Flag.create();
336               var first = (Map) firstEntry;
337               first.keySet().forEach(x -> {
338                  addComma.ifSet(() -> w.w(',')).set();
339                  // Apply trimStrings to map keys as well
340                  Object keyVal;
341                  if (x == null)
342                     keyVal = nullValue;
343                  else if (x instanceof String x2)
344                     keyVal = toString(x2);
345                  else
346                     keyVal = x;
347                  w.writeEntry(keyVal);
348               });
349               if (addTypeColumn && ine(typeColName)) {
350                  w.w(',');
351                  w.writeEntry(typeColName);
352               }
353               w.append('\n');
354               l.forEach(x -> {
355                  var addComma2 = Flag.create();
356                  var swapped = applySwap(x, getClassMetaForObject(x));
357                  var aType = getClassMetaForObject(swapped);
358                  var map = (Map) swapped;
359                  map.values().forEach(y -> {
360                     addComma2.ifSet(() -> w.w(',')).set();
361                     var value = applySwap(y, getClassMetaForObject(y));
362                     value = formatForCsvCell(value);
363                     // Apply trimStrings to map values
364                     if (value instanceof String value2) value = toString(value2);
365                     w.writeEntry(or(value, nullValue));
366                  });
367                  if (addTypeColumn && ine(typeColName)) {
368                     var typeName = getBeanTypeName(this, eType, aType, null);
369                     w.w(',');
370                     w.writeEntry(or(typeName, ""));
371                  }
372                  w.w('\n');
373               });
374            } else {
375               // Simple value path: single "value" column + optional _type
376               w.writeEntry("value");
377               if (addTypeColumn && ine(typeColName)) {
378                  w.w(',');
379                  w.writeEntry(typeColName);
380               }
381               w.append('\n');
382               l.forEach(x -> {
383                  var value = applySwap(x, getClassMetaForObject(x));
384                  value = formatForCsvCell(value);
385                  // Use toString() to respect trimStrings setting
386                  w.writeEntry(value != null ? toString(value) : nullValue);
387                  if (addTypeColumn && ine(typeColName)) {
388                     if (x != null) {
389                        var aType = getClassMetaForObject(x);
390                        var typeName = getBeanTypeName(this, eType, aType, null);
391                        w.w(',');
392                        w.writeEntry(or(typeName, ""));
393                     } else {
394                        w.w(',');
395                        w.writeEntry("");
396                     }
397                  }
398                  w.w('\n');
399               });
400            }
401         }
402         }
403      } finally {
404         pop();
405      }
406   }
407
408
409   private Object formatIfDateOrDuration(Object value) {
410      if (value == null)
411         return null;
412      var cm = getClassMetaForObject(value);
413      if (value instanceof Date value2)
414         return writeDate(value2, cm);
415      if (value instanceof Calendar || value instanceof javax.xml.datatype.XMLGregorianCalendar)
416         return writeCalendar(value, cm);
417      if (value instanceof TemporalAccessor value2)
418         return writeTemporal(value2, cm);
419      if (value instanceof Duration)
420         return value.toString();
421      return value;
422   }
423
424   /**
425    * Formats a value for a CSV cell, handling byte[], primitive arrays, and nested structures.
426    */
427   private Object formatForCsvCell(Object value) {
428      if (value == null)
429         return null;
430      if (allowNestedStructures) {
431         var type = getClassMetaForObject(value);
432         if (value instanceof Map || value instanceof Collection || value instanceof Object[]
433               || (type.isBean() && !(value instanceof Map)))
434            return new CsvCellSerializer(byteArrayFormat, nullValue).write(value, this);
435      }
436      if (value instanceof byte[] value2) {
437         return byteArrayFormat == CsvByteArrayCellFormat.SEMICOLON_DELIMITED
438            ? formatByteArraySemicolon(value2)
439            : base64Encode(value2);
440      }
441      if (value instanceof int[] value2) {
442         var sb = new StringBuilder();
443         sb.append('[');
444         for (var i = 0; i < value2.length; i++) {
445            if (i > 0) sb.append(';');
446            sb.append(value2[i]);
447         }
448         sb.append(']');
449         return sb.toString();
450      }
451      if (value instanceof long[] value2) {
452         var sb = new StringBuilder();
453         sb.append('[');
454         for (var i = 0; i < value2.length; i++) {
455            if (i > 0) sb.append(';');
456            sb.append(value2[i]);
457         }
458         sb.append(']');
459         return sb.toString();
460      }
461      if (value instanceof double[] value2) {
462         var sb = new StringBuilder();
463         sb.append('[');
464         for (var i = 0; i < value2.length; i++) {
465            if (i > 0) sb.append(';');
466            sb.append(value2[i]);
467         }
468         sb.append(']');
469         return sb.toString();
470      }
471      if (value instanceof float[] value2) {
472         var sb = new StringBuilder();
473         sb.append('[');
474         for (var i = 0; i < value2.length; i++) {
475            if (i > 0) sb.append(';');
476            sb.append(value2[i]);
477         }
478         sb.append(']');
479         return sb.toString();
480      }
481      if (value instanceof short[] value2) {
482         var sb = new StringBuilder();
483         sb.append('[');
484         for (var i = 0; i < value2.length; i++) {
485            if (i > 0) sb.append(';');
486            sb.append(value2[i]);
487         }
488         sb.append(']');
489         return sb.toString();
490      }
491      if (value instanceof boolean[] value2) {
492         var sb = new StringBuilder();
493         sb.append('[');
494         for (var i = 0; i < value2.length; i++) {
495            if (i > 0) sb.append(';');
496            sb.append(value2[i]);
497         }
498         sb.append(']');
499         return sb.toString();
500      }
501      if (value instanceof char[] value2) {
502         var sb = new StringBuilder();
503         sb.append('[');
504         for (var i = 0; i < value2.length; i++) {
505            if (i > 0) sb.append(';');
506            sb.append((int) value2[i]);
507         }
508         sb.append(']');
509         return sb.toString();
510      }
511      return value;
512   }
513
514   private static String formatByteArraySemicolon(byte[] b) {
515      var sb = new StringBuilder();
516      for (var i = 0; i < b.length; i++) {
517         if (i > 0) sb.append(';');
518         sb.append(b[i] & 0xff);
519      }
520      return sb.toString();
521   }
522
523   /**
524    * Prepares a value for inline cell serialization (bean→Map, date format, etc.).
525    * Used by {@link CsvCellSerializer}.
526    */
527   Object prepareForInlineValue(Object value) {
528      if (value == null)
529         return null;
530      var swapped = applySwap(value, getClassMetaForObject(value));
531      var type = getClassMetaForObject(swapped);
532      if (type.isBean() && !(swapped instanceof Map))
533         return toBeanMap(swapped);
534      if (swapped instanceof Date swapped2)
535         return writeDate(swapped2, type);
536      if (swapped instanceof Calendar || swapped instanceof XMLGregorianCalendar)
537         return writeCalendar(swapped, type);
538      if (swapped instanceof TemporalAccessor swapped2)
539         return writeTemporal(swapped2, type);
540      if (swapped instanceof Duration)
541         return swapped.toString();
542      return swapped;
543   }
544
545   CsvWriter getCsvWriter(SerializerPipe out) {
546      var output = out.getRawOutput();
547      if (output instanceof CsvWriter output2)
548         return output2;
549      var w = new CsvWriter(out.getWriter(), isUseWhitespace(), getMaxIndent(), getQuoteChar(), isTrimStrings(), getUriResolver()).neutralizeFormulas(neutralizeFormulas);
550      out.setWriter(w);
551      return w;
552   }
553}