001package io.avaje.json.stream;
002
003import io.avaje.json.JsonReader;
004import io.avaje.json.JsonWriter;
005import io.avaje.json.PropertyNames;
006import io.avaje.json.stream.core.JsonStreamBuilder;
007
008import java.io.*;
009
010/**
011 * Provides the underlying JsonReader and JsonWriter to use.
012 */
013public interface JsonStream {
014
015  /**
016   * Return the JsonReader given json string content.
017   */
018  JsonReader reader(String json);
019
020  /**
021   * Return the JsonReader given json content as bytes.
022   */
023  JsonReader reader(byte[] json);
024
025  /**
026   * Return the JsonReader given json string content.
027   */
028  JsonReader reader(Reader reader);
029
030  /**
031   * Return the JsonReader given json string content.
032   */
033  JsonReader reader(InputStream inputStream);
034
035  /**
036   * Return the JsonWriter given writer to use.
037   */
038  JsonWriter writer(Writer writer);
039
040  /**
041   * Return the JsonWriter given the outputStream.
042   */
043  JsonWriter writer(OutputStream outputStream);
044
045  /**
046   * Return the JsonWriter given the output.
047   */
048  JsonWriter writer(JsonOutput output);
049
050  /**
051   * Return a JsonWriter for use for writing to json string.
052   */
053  BufferedJsonWriter bufferedWriter();
054
055  /**
056   * Return a JsonWriter to use for writing json to byte array.
057   */
058  BytesJsonWriter bufferedWriterAsBytes();
059
060  /**
061   * Return PropertyNames given the names of properties.
062   * <p>
063   * The PropertyNames can prepare the names for writing such as
064   * escaping quotes and encoding to bytes so that the names can
065   * be written more efficiently.
066   *
067   * @see JsonWriter#allNames(PropertyNames)
068   * @see JsonWriter#name(int)
069   */
070  PropertyNames properties(String... names);
071
072  /**
073   * Create and return a builder for the default JsonStreamAdapter implementation.
074   */
075  static Builder builder() {
076    return new JsonStreamBuilder();
077  }
078
079  /** Used to build JsonStream with custom settings. */
080  interface Builder {
081
082    /** Set to true to serialize nulls. Defaults to false. */
083    Builder serializeNulls(boolean serializeNulls);
084
085    /** Set to true to serialize empty collections. Defaults to false. */
086    Builder serializeEmpty(boolean serializeEmpty);
087
088    /** Set to true to fail on unknown properties. Defaults to false. */
089    Builder failOnUnknown(boolean failOnUnknown);
090
091    /** Set to true to fail on NULL for primitive types. Defaults to false. */
092    Builder failOnNullPrimitives(boolean failOnNullPrimitives);
093
094    /** Determines how byte buffers are recycled */
095    Builder bufferRecycling(BufferRecycleStrategy strategy);
096
097    /** Build and return the JsonStream. */
098    JsonStream build();
099  }
100}