001/*
002 * Copyright (C) 2014 Square, Inc.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *    https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package io.avaje.json;
017
018import java.io.Closeable;
019import java.io.Flushable;
020import java.math.BigDecimal;
021import java.math.BigInteger;
022
023/**
024 * Writes json content.
025 */
026public interface JsonWriter extends Closeable, Flushable {
027
028  /**
029   * Unwrap the underlying generator being used.
030   * <p>
031   * We do this to get access to the underlying generator. For the case when
032   * using jackson-core we get access to Jackson JsonGenerator and can then
033   * do Jackson specific things like set custom escaping.
034   *
035   * <pre>{@code
036   *
037   *     try (JsonWriter writer = jsonb.writer(new StringWriter())) {
038   *
039   *       // get access to the underlying Jackson JsonGenerator
040   *       var generator = writer.unwrap(JsonGenerator.class)
041   *
042   *       // do Jackson specific things like ...
043   *       generator.setCharacterEscapes(new HTMLCharacterEscapes());
044   *
045   *       jsonb.toJson(myBean, writer);
046   *     }
047   *
048   * }</pre>
049   */
050  <T> T unwrap(Class<T> type);
051
052  /**
053   * Set to serialise null values or not.
054   */
055  void serializeNulls(boolean serializeNulls);
056
057  /**
058   * Return true if null values should be serialised.
059   */
060  boolean serializeNulls();
061
062  /**
063   * Set to serialise empty collections or not.
064   */
065  void serializeEmpty(boolean serializeEmpty);
066
067  /**
068   * Return true if empty collections should be serialised.
069   */
070  boolean serializeEmpty();
071
072  /**
073   * Set tp true to output json in pretty format.
074   */
075  void pretty(boolean pretty);
076
077  /**
078   * Return the current path.
079   */
080  String path();
081
082  /**
083   * Set the property names that will be used for all json generation.
084   * <p>
085   * These names should be used for all json generation for this generator and set once
086   * rather than set per object via {@link #beginObject(PropertyNames)} (PropertyNames)}.
087   * <p>
088   * This is used by view json generation where all the names are known at the point
089   * when the view is created (a sort of flattened nested tree).
090   */
091  void allNames(PropertyNames names);
092
093  /**
094   * Set the next property name to write by position. This uses the already encoded
095   * name values of PropertyNames.
096   */
097  void name(int position);
098
099  /**
100   * Set the next property name to write.
101   * <p>
102   * This is generally less efficient than using {@link JsonWriter#beginObject(PropertyNames)}
103   * and {@link JsonWriter#name(int)}.
104   */
105  void name(String name);
106
107  /**
108   * Write array begin.
109   */
110  void beginArray();
111
112  /**
113   * Write array end.
114   */
115  void endArray();
116
117  /**
118   * Write empty array.
119   */
120  void emptyArray();
121
122  /**
123   * Write object begin.
124   */
125  void beginObject();
126
127  /**
128   * Write object being and use the already encoded property names.
129   */
130  void beginObject(PropertyNames names);
131
132  /**
133   * Write object end.
134   */
135  void endObject();
136
137  /**
138   * Write null value.
139   */
140  void nullValue();
141
142  /**
143   * Write a string value.
144   */
145  void value(String value);
146
147  /**
148   * Write a boolean value.
149   */
150  void value(boolean value);
151
152  /**
153   * Write an int value.
154   */
155  void value(int value);
156
157  /**
158   * Write a long value.
159   */
160  void value(long value);
161
162  /**
163   * Write a double value.
164   */
165  void value(double value);
166
167  /**
168   * Write a Boolean value.
169   */
170  void value(Boolean value);
171
172  /**
173   * Write an Integer value.
174   */
175  void value(Integer value);
176
177  /**
178   * Write a Long value.
179   */
180  void value(Long value);
181
182  /**
183   * Write a Double value.
184   */
185  void value(Double value);
186
187  /**
188   * Write a BigDecimal value.
189   */
190  void value(BigDecimal value);
191
192  /**
193   * Write a BigInteger value.
194   */
195  void value(BigInteger value);
196
197  /**
198   * Write binary content as base64.
199   */
200  void value(byte[] value);
201
202  /**
203   * Write a value that could be any value.
204   */
205  void jsonValue(Object value);
206
207  /**
208   * Write raw JSON content.
209   */
210  void rawValue(String value);
211
212  /**
213   * Write new line characters typically for {@code x-json-stream} content.
214   */
215  void writeNewLine();
216
217  /**
218   * Flush the writer.
219   */
220  void flush();
221
222  /**
223   * Close the writer.
224   */
225  void close();
226
227  /**
228   * Mark the generated json as not completed due to an error.
229   * <p>
230   * This typically means not to flush or close an underlying OutputStream which
231   * allows it to be reset to then write some error response content instead.
232   */
233  void markIncomplete();
234}