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.jsonl; 018 019import org.apache.juneau.marshall.json.*; 020import org.apache.juneau.marshall.swap.spi.*; 021 022/** 023 * Serializes POJO models to JSONL (JSON Lines). 024 * 025 * <h2 class='topic'>Media types</h2> 026 * <p> 027 * Handles <c>Accept</c> types: <bc>application/jsonl, application/jsonlines, application/x-ndjson, text/jsonl</bc> 028 * <p> 029 * Produces <c>Content-Type</c> types: <bc>application/jsonl</bc> 030 * 031 * <h2 class='topic'>Description</h2> 032 * <p> 033 * Serializes POJOs to JSONL format where each top-level value is written as a compact JSON 034 * value on its own line. The conversion is as follows... 035 * <ul class='spaced-list'> 036 * <li>Maps and beans are converted to JSON objects, one per line. 037 * <li>Collections and arrays are converted to one JSON value per line (no wrapping brackets). 038 * <li>Strings are converted to JSON strings, one per line. 039 * <li>Numbers are converted to JSON numbers, one per line. 040 * <li>Booleans are converted to JSON booleans, one per line. 041 * <li>Nulls are converted to JSON nulls, one per line. 042 * <li>Nested objects and collections remain compact on a single line per outer element. 043 * </ul> 044 * <p> 045 * Non-JSON-primitive types are transformed through 046 * {@link ObjectSwap ObjectSwaps}. 047 * 048 * <h2 class='section'>Example:</h2> 049 * <p class='bjava'> 050 * <jc>// Use the default serializer to serialize a list of POJOs</jc> 051 * String <jv>jsonl</jv> = JsonlSerializer.<jsf>DEFAULT</jsf>.write(<jv>myList</jv>); 052 * 053 * <jc>// Create a custom serializer</jc> 054 * JsonlSerializer <jv>serializer</jv> = JsonlSerializer.<jsm>create</jsm>().build(); 055 * 056 * <jc>// Clone an existing serializer</jc> 057 * <jv>serializer</jv> = JsonlSerializer.<jsf>DEFAULT</jsf>.copy().build(); 058 * 059 * <jc>// Serialize a list of POJOs to JSONL</jc> 060 * String <jv>jsonl</jv> = <jv>serializer</jv>.write(<jv>myList</jv>); 061 * </p> 062 * 063 * <h2 class='figure'>Example output (List of beans):</h2> 064 * <p class='bjson'> 065 * {"name":"Alice","age":30} 066 * {"name":"Bob","age":25} 067 * {"name":"Carol","age":35} 068 * </p> 069 * 070 * <h2 class='figure'>Complex (bean with nested object and array):</h2> 071 * <p class='bjson'> 072 * {"name":"Alice","age":30,"address":{"street":"123 Main St","city":"Boston"},"tags":["a","b","c"]} 073 * {"name":"Bob","age":25,"address":{"street":"456 Oak Ave","city":"Portland"},"tags":["d","e"]} 074 * </p> 075 * 076 * <h2 class='section'>Limitations compared to JSON</h2> 077 * <ul class='spaced-list'> 078 * <li><b>No pretty-printing</b>: {@link org.apache.juneau.marshall.serializer.WriterSerializer.Builder#useWhitespace() useWhitespace()} 079 * is always suppressed. JSONL requires each JSON value to fit on a single line; 080 * applying intra-line pretty-printing would embed newlines and produce invalid JSONL. 081 * The setting is silently ignored regardless of its configured value. 082 * <li><b>Top-level semantics differ</b>: Collections and arrays are unwrapped — each element 083 * becomes one line. A single non-collection object produces one JSONL line. 084 * </ul> 085 * 086 * <h2 class='section'>Notes:</h2><ul> 087 * <li class='note'>This class is thread safe and reusable. 088 * </ul> 089 * 090 * <h2 class='section'>See Also:</h2><ul> 091 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JsonlSupport">JSONL</a> 092 * </ul> 093 */ 094@SuppressWarnings({ 095 "java:S110", // Inheritance depth acceptable 096 "java:S9149" // Per-format static factories intentionally shadow the parent's. 097}) 098public class JsonlSerializer extends JsonSerializer { 099 100 /** Default serializer. */ 101 public static final JsonlSerializer DEFAULT = new JsonlSerializer(create()); 102 103 /** 104 * Creates a new builder for this object. 105 * 106 * @return A new builder. 107 */ 108 @SuppressWarnings({ 109 "java:S1452" // Builder<?> wildcard return intentional; callers chain via fluent API without needing the concrete type 110 }) 111 public static JsonSerializer.Builder<?> create() { 112 return JsonSerializer.create() 113 .produces("application/jsonl") 114 .accept("application/jsonl,application/jsonlines,application/x-ndjson,text/jsonl") 115 .type(JsonlSerializer.class) 116 .useWhitespace(false); 117 } 118 119 /** 120 * Constructor. 121 * 122 * @param builder The builder for this object. 123 */ 124 public JsonlSerializer(JsonSerializer.Builder<?> builder) { 125 super(builder.useWhitespace(false)); 126 } 127 128 @Override /* Overridden from Context */ 129 public JsonlSerializerSession.Builder createSession() { 130 return JsonlSerializerSession.create(this); 131 } 132 133}