code: /* Jackson JSON-processor.
   *
   * Copyright (c) 2007- Tatu Saloranta, tatu.saloranta@iki.fi
   *
   * Licensed under the License specified in file Jackson.LICENSE, included with
   * the source code and binary code bundles.
   * You may not use this file except in compliance with the License.
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.gridkit.jvmtool.util.json;
  
  import java.io.IOException;
  import java.math.BigDecimal;
  import java.math.BigInteger;
  
  import org.gridkit.jvmtool.jackson.JsonGenerator;
  
  /**
   * This is stripped down version of {@link JsonGenerator}.
   *
   * @author Alexey Ragozin (alexey.ragozin@gmail.com)
   */
  public interface JsonStreamWriter {
  
      /*
      /**********************************************************
      /* Public API, write methods, structural
      /**********************************************************
       */
  
      /**
       * Method for writing starting marker of a JSON Array value
       * (character '['; plus possible white space decoration
       * if pretty-printing is enabled).
       *<p>
       * Array values can be written in any context where values
       * are allowed: meaning everywhere except for when
       * a field name is expected.
       */
      public void writeStartArray() throws IOException;
  
      /**
       * Method for writing closing marker of a JSON Array value
       * (character ']'; plus possible white space decoration
       * if pretty-printing is enabled).
       *<p>
       * Marker can be written if the innermost structured type
       * is Array.
       */
      public void writeEndArray() throws IOException;
  
      /**
       * Method for writing starting marker of a JSON Object value
       * (character '{'; plus possible white space decoration
       * if pretty-printing is enabled).
       *<p>
       * Object values can be written in any context where values
       * are allowed: meaning everywhere except for when
       * a field name is expected.
       */
      public void writeStartObject() throws IOException;
  
      /**
       * Method for writing closing marker of a JSON Object value
       * (character '}'; plus possible white space decoration
       * if pretty-printing is enabled).
       *<p>
       * Marker can be written if the innermost structured type
       * is Object, and the last written event was either a
       * complete value, or START-OBJECT marker (see JSON specification
       * for more details).
       */
      public void writeEndObject() throws IOException;
  
      /**
       * Method for writing a field name (JSON String surrounded by
       * double quotes: syntactically identical to a JSON String value),
       * possibly decorated by white space if pretty-printing is enabled.
       *<p>
       * Field names can only be written in Object context (check out
       * JSON specification for details), when field name is expected
       * (field names alternate with values).
       */
      public void writeFieldName(String name) throws IOException;
  
      /*
      /**********************************************************
      /* Public API, write methods, text/String values
      /**********************************************************
       */
  
      /**
       * Method for outputting a String value. Depending on context
       * this means either array element, (object) field value or
       * a stand alone String; but in all cases, String will be
       * surrounded in double quotes, and contents will be properly
       * escaped as required by JSON specification.
       */
      public void writeString(String text) throws IOException;
  
      /**
       * Method for outputting a String value. Depending on context
       * this means either array element, (object) field value or
       * a stand alone String; but in all cases, String will be
       * surrounded in double quotes, and contents will be properly
       * escaped as required by JSON specification.
       */
      public void writeString(char[] text, int offset, int len) throws IOException;
  
      /**
       * Method similar to {@link #writeString(String)} but that takes as
       * its input a UTF-8 encoded String that is to be output as-is, without additional
       * escaping (type of which depends on data format; backslashes for JSON).
       * However, quoting that data format requires (like double-quotes for JSON) will be added
       * around the value if and as necessary.
       *<p>
       * Note that some backends may choose not to support this method: for
       * example, if underlying destination is a {@link java.io.Writer}
       * using this method would require UTF-8 decoding.
       * If so, implementation may instead choose to throw a
       * {@link UnsupportedOperationException} due to ineffectiveness
       * of having to decode input.
       *
       * @since 1.7
       */
      public void writeRawUTF8String(byte[] text, int offset, int length) throws IOException;
  
      /**
       * Method similar to {@link #writeString(String)} but that takes as its input
       * a UTF-8 encoded String which has <b>not</b> been escaped using whatever
       * escaping scheme data format requires (for JSON that is backslash-escaping
       * for control characters and double-quotes; for other formats something else).
       * This means that textual JSON backends need to check if value needs
       * JSON escaping, but otherwise can just be copied as is to output.
       * Also, quoting that data format requires (like double-quotes for JSON) will be added
       * around the value if and as necessary.
       *<p>
       * Note that some backends may choose not to support this method: for
       * example, if underlying destination is a {@link java.io.Writer}
       * using this method would require UTF-8 decoding.
       * In this case
       * generator implementation may instead choose to throw a
       * {@link UnsupportedOperationException} due to ineffectiveness
       * of having to decode input.
       *
       * @since 1.7
       */
      public void writeUTF8String(byte[] text, int offset, int length) throws IOException;
  
      /*
      /**********************************************************
      /* Public API, write methods, binary/raw content
      /**********************************************************
       */
  
      /**
       * Method that will force generator to copy
       * input text verbatim with <b>no</b> modifications (including
       * that no escaping is done and no separators are added even
       * if context [array, object] would otherwise require such).
       * If such separators are desired, use
       * {@link #writeRawValue(String)} instead.
       *<p>
       * Note that not all generator implementations necessarily support
       * such by-pass methods: those that do not will throw
       * {@link UnsupportedOperationException}.
       */
      public void writeRaw(String text) throws IOException;
  
      /**
       * Method that will force generator to copy
       * input text verbatim with <b>no</b> modifications (including
       * that no escaping is done and no separators are added even
       * if context [array, object] would otherwise require such).
       * If such separators are desired, use
       * {@link #writeRawValue(String)} instead.
       *<p>
       * Note that not all generator implementations necessarily support
       * such by-pass methods: those that do not will throw
       * {@link UnsupportedOperationException}.
       */
      public void writeRaw(String text, int offset, int len) throws IOException;
  
      /**
       * Method that will force generator to copy
       * input text verbatim with <b>no</b> modifications (including
       * that no escaping is done and no separators are added even
       * if context [array, object] would otherwise require such).
       * If such separators are desired, use
       * {@link #writeRawValue(String)} instead.
       *<p>
       * Note that not all generator implementations necessarily support
       * such by-pass methods: those that do not will throw
       * {@link UnsupportedOperationException}.
       */
      public void writeRaw(char[] text, int offset, int len) throws IOException;
  
      /**
       * Method that will force generator to copy
       * input text verbatim with <b>no</b> modifications (including
       * that no escaping is done and no separators are added even
       * if context [array, object] would otherwise require such).
       * If such separators are desired, use
       * {@link #writeRawValue(String)} instead.
       *<p>
       * Note that not all generator implementations necessarily support
       * such by-pass methods: those that do not will throw
       * {@link UnsupportedOperationException}.
       */
      public void writeRaw(char c) throws IOException;
  
      /**
       * Method that will force generator to copy
       * input text verbatim without any modifications, but assuming
       * it must constitute a single legal JSON value (number, string,
       * boolean, null, Array or List). Assuming this, proper separators
       * are added if and as needed (comma or colon), and generator
       * state updated to reflect this.
       */
      public void writeRawValue(String text) throws IOException;
  
      public void writeRawValue(String text, int offset, int len) throws IOException;
  
      public void writeRawValue(char[] text, int offset, int len) throws IOException;
  
      /*
      /**********************************************************
      /* Public API, write methods, other value types
      /**********************************************************
       */
  
      /**
       * Method for outputting given value as Json number.
       * Can be called in any context where a value is expected
       * (Array value, Object field value, root-level value).
       * Additional white space may be added around the value
       * if pretty-printing is enabled.
       */
      public void writeNumber(int v) throws IOException;
  
      /**
       * Method for outputting given value as Json number.
       * Can be called in any context where a value is expected
       * (Array value, Object field value, root-level value).
       * Additional white space may be added around the value
       * if pretty-printing is enabled.
       */
      public void writeNumber(long v) throws IOException;
  
      /**
       * Method for outputting given value as Json number.
       * Can be called in any context where a value is expected
       * (Array value, Object field value, root-level value).
       * Additional white space may be added around the value
       * if pretty-printing is enabled.
       */
      public void writeNumber(BigInteger v) throws IOException;
  
      /**
       * Method for outputting indicate Json numeric value.
       * Can be called in any context where a value is expected
       * (Array value, Object field value, root-level value).
       * Additional white space may be added around the value
       * if pretty-printing is enabled.
       */
      public void writeNumber(double d) throws IOException;
  
      /**
       * Method for outputting indicate Json numeric value.
       * Can be called in any context where a value is expected
       * (Array value, Object field value, root-level value).
       * Additional white space may be added around the value
       * if pretty-printing is enabled.
       */
      public void writeNumber(float f) throws IOException;
  
      /**
       * Method for outputting indicate Json numeric value.
       * Can be called in any context where a value is expected
       * (Array value, Object field value, root-level value).
       * Additional white space may be added around the value
       * if pretty-printing is enabled.
       */
      public void writeNumber(BigDecimal dec) throws IOException;
  
      /**
       * Write method that can be used for custom numeric types that can
       * not be (easily?) converted to "standard" Java number types.
       * Because numbers are not surrounded by double quotes, regular
       * {@link #writeString} method can not be used; nor
       * {@link #writeRaw} because that does not properly handle
       * value separators needed in Array or Object contexts.
       *<p>
       * Note: because of lack of type safety, some generator
       * implementations may not be able to implement this
       * method. For example, if a binary json format is used,
       * it may require type information for encoding; similarly
       * for generator-wrappers around Java objects or Json nodes.
       * If implementation does not implement this method,
       * it needs to throw {@link UnsupportedOperationException}.
       */
      public void writeNumber(String encodedValue) throws IOException, UnsupportedOperationException;
  
      /**
       * Method for outputting literal Json boolean value (one of
       * Strings 'true' and 'false').
       * Can be called in any context where a value is expected
       * (Array value, Object field value, root-level value).
       * Additional white space may be added around the value
       * if pretty-printing is enabled.
       */
      public void writeBoolean(boolean state) throws IOException;
  
      /**
       * Method for outputting literal Json null value.
       * Can be called in any context where a value is expected
       * (Array value, Object field value, root-level value).
       * Additional white space may be added around the value
       * if pretty-printing is enabled.
       */
      public void writeNull() throws IOException;
  
      /*
      /**********************************************************
      /* Public API, convenience field write methods
      /**********************************************************
       */
  
      /**
       * Convenience method for outputting a field entry ("member")
       * that has a String value. Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeString(value);
       *</pre>
       *<p>
       * Note: many performance-sensitive implementations override this method
       */
      public void writeStringField(String fieldName, String value) throws IOException;
  
      /**
       * Convenience method for outputting a field entry ("member")
       * that has a boolean value. Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeBoolean(value);
       *</pre>
       */
      public void writeBooleanField(String fieldName, boolean value) throws IOException;
  
      /**
       * Convenience method for outputting a field entry ("member")
       * that has JSON literal value null. Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeNull();
       *</pre>
       */
      public void writeNullField(String fieldName) throws IOException;
  
      /**
       * Convenience method for outputting a field entry ("member")
       * that has the specified numeric value. Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeNumber(value);
       *</pre>
       */
      public void writeNumberField(String fieldName, int value) throws IOException;
  
      /**
       * Convenience method for outputting a field entry ("member")
       * that has the specified numeric value. Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeNumber(value);
       *</pre>
       */
      public void writeNumberField(String fieldName, long value) throws IOException;
  
      /**
       * Convenience method for outputting a field entry ("member")
       * that has the specified numeric value. Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeNumber(value);
       *</pre>
       */
      public void writeNumberField(String fieldName, double value) throws IOException;
  
      /**
       * Convenience method for outputting a field entry ("member")
       * that has the specified numeric value. Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeNumber(value);
       *</pre>
       */
      public void writeNumberField(String fieldName, float value) throws IOException;
  
      /**
       * Convenience method for outputting a field entry ("member")
       * that has the specified numeric value.
       * Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeNumber(value);
       *</pre>
       */
      public void writeNumberField(String fieldName, BigDecimal value) throws IOException;
  
      /**
       * Convenience method for outputting a field entry ("member")
       * (that will contain a JSON Array value), and the START_ARRAY marker.
       * Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeStartArray();
       *</pre>
       *<p>
       * Note: caller still has to take care to close the array
       * (by calling {#link #writeEndArray}) after writing all values
       * of the value Array.
       */
      public void writeArrayFieldStart(String fieldName) throws IOException;
  
      /**
       * Convenience method for outputting a field entry ("member")
       * (that will contain a JSON Object value), and the START_OBJECT marker.
       * Equivalent to:
       *<pre>
       *  writeFieldName(fieldName);
       *  writeStartObject();
       *</pre>
       *<p>
       * Note: caller still has to take care to close the Object
       * (by calling {#link #writeEndObject}) after writing all
       * entries of the value Object.
       */
      public void writeObjectFieldStart(String fieldName) throws IOException;
  }
  