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("<NULL>")} (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 — each {@link RecordWriter#write(Object) write(...)} call appends 309 * one row — 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}