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}