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