javax.json.stream.JsonGenerator Maven / Gradle / Ivy
The newest version!
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.json.stream;
import javax.json.JsonValue;
import java.io.Closeable;
import java.io.Flushable;
import java.math.BigDecimal;
import java.math.BigInteger;
/**
* Writes JSON data to an output source in a streaming way. The class
* {@link javax.json.Json} contains methods to create generators for character
* or output streams ({@link java.io.Writer} and {@link java.io.OutputStream}).
*
*
* The following example shows how to create a JSON generator:
*
*
* JsonGenerator generator = Json.createGenerator(...);
*
*
*
*
* The class {@link JsonGeneratorFactory} also contains methods to create
* {@code JsonGenerator} instances. {@link JsonGeneratorFactory} should be used
* when creating multiple generator instances, as in the following example:
*
*
* JsonGeneratorFactory factory = Json.createGeneratorFactory();
* JsonGenerator generator1 = factory.createGenerator(...);
* JsonGenerator generator2 = factory.createGenerator(...);
*
*
*
*
* JSON objects can be created using {@code JsonGenerator} by calling the
* {@link #writeStartObject()} method and then adding name/value pairs with the
* {@code write} method.
*
* The following example shows how to generate an empty JSON object:
*
*
* JsonGenerator generator = ...;
* generator.writeStartObject().writeEnd().close();
*
*
*
* JSON arrays can be created using {@code JsonGenerator} by calling the
* {@link #writeStartArray()} method and then adding values with the
* {@code write} method.
*
*
* The following example shows how to generate an empty JSON array:
*
*
* JsonGenerator generator = ...;
* generator.writeStartArray().writeEnd().close();
*
*
*
*
* Other JSON values (that are not JSON objects or arrays) can be created
* by calling the appropiate {@code write} methods.
*
* The following example shows how to generate a JSON string:
*
* JsonGenerator generator = ...;
* generator.write("message").close();
*
*
* {@code JsonGenerator} methods can be chained as in the following example:
*
*
* generator
* .writeStartObject()
* .write("firstName", "John")
* .write("lastName", "Smith")
* .write("age", 25)
* .writeStartObject("address")
* .write("streetAddress", "21 2nd Street")
* .write("city", "New York")
* .write("state", "NY")
* .write("postalCode", "10021")
* .writeEnd()
* .writeStartArray("phoneNumber")
* .writeStartObject()
* .write("type", "home")
* .write("number", "212 555-1234")
* .writeEnd()
* .writeStartObject()
* .write("type", "fax")
* .write("number", "646 555-4567")
* .writeEnd()
* .writeEnd()
* .writeEnd();
* generator.close();
*
*
*
* The example code above generates the following JSON (or equivalent):
*
*
* {
* "firstName": "John", "lastName": "Smith", "age": 25,
* "address" : {
* "streetAddress": "21 2nd Street",
* "city": "New York",
* "state": "NY",
* "postalCode": "10021"
* },
* "phoneNumber": [
* {"type": "home", "number": "212 555-1234"},
* {"type": "fax", "number": "646 555-4567"}
* ]
* }
*
*
*
* The generated JSON text must strictly conform to the grammar defined in
* RFC 7159.
*
* @see javax.json.Json
* @see JsonGeneratorFactory
*/
public interface JsonGenerator extends Flushable, /*Auto*/Closeable {
/**
* Configuration property to generate JSON prettily. All providers
* must support this property. The value of the property could be
* be anything.
*/
String PRETTY_PRINTING = "javax.json.stream.JsonGenerator.prettyPrinting" ;
/**
* Writes the JSON start object character. It starts a new child object
* context within which JSON name/value pairs can be written to the object.
* This method is valid only in an array context, field context or in no context (when a
* context is not yet started). This method can only be called once in
* no context.
*
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is called within an
* object context or if it is called more than once in no context.
*/
JsonGenerator writeStartObject();
/**
* Writes the JSON name/start object character pair in the current
* object context. It starts a new child object context within which JSON
* name/value pairs can be written to the object.
*
* @param name a name within the JSON name/object pair to be written
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context
*/
JsonGenerator writeStartObject(String name);
/**
* Writes the JSON name with a colon. It starts a field context, in which valid
* options are writing a value, starting an object or an array.
*
* Writing value closes field context, if object or array is started after field name,
* field context will be closed after object/array close.
*
* @param name name of json field
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context
*
* @since 1.1
*/
JsonGenerator writeKey(String name);
/**
* Writes the JSON start array character. It starts a new child array
* context within which JSON values can be written to the array. This
* method is valid only in an array context, field context or in no context (when a
* context is not yet started). This method can only be called once in
* no context.
*
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is called within an
* object context or if called more than once in no context
*/
JsonGenerator writeStartArray();
/**
* Writes the JSON name/start array character pair with in the current
* object context. It starts a new child array context within which JSON
* values can be written to the array.
*
* @param name a name within the JSON name/array pair to be written
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within
* an object context
*/
JsonGenerator writeStartArray(String name);
/**
* Writes a JSON name/value pair in the current object context.
*
* @param name a name in the JSON name/value pair to be written in
* current JSON object
* @param value a value in the JSON name/value pair to be written in
* current JSON object
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context
*/
JsonGenerator write(String name, JsonValue value);
/**
* Writes a JSON name/string value pair in the current object context.
* The specified value is written as JSON string value.
*
* @param name a name in the JSON name/string pair to be written in
* current JSON object
* @param value a value in the JSON name/string pair to be written in
* current JSON object
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context
*/
JsonGenerator write(String name, String value);
/**
* Writes a JSON name/number value pair in the current object context.
* The specified value is written as a JSON number value. The string
* {@code new BigDecimal(value).toString()}
* is used as the text value for writing.
*
* @param name a name in the JSON name/number pair to be written in
* current JSON object
* @param value a value in the JSON name/number pair to be written in
* current JSON object
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context.
*/
JsonGenerator write(String name, BigInteger value);
/**
* Writes a JSON name/number value pair in the current object context.
* The specified value is written as a JSON number value. The specified
* value's {@code toString()} is used as the text value for writing.
*
* @param name a name in the JSON name/number pair to be written in
* current JSON object
* @param value a value in the JSON name/number pair to be written in
* current JSON object
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context.
*/
JsonGenerator write(String name, BigDecimal value);
/**
* Writes a JSON name/number value pair in the current object context.
* The specified value is written as a JSON number value. The string
* {@code new BigDecimal(value).toString()} is used as the text value
* for writing.
*
* @param name a name in the JSON name/number pair to be written in
* current JSON object
* @param value a value in the JSON name/number pair to be written in
* current JSON object
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context.
*/
JsonGenerator write(String name, int value);
/**
* Writes a JSON name/number value pair in the current object context.
* The specified value is written as a JSON number value. The string
* {@code new BigDecimal(value).toString()} is used as the text
* value for writing.
*
* @param name a name in the JSON name/number pair to be written in
* current JSON object
* @param value a value in the JSON name/number pair to be written in
* current JSON object
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context.
*/
JsonGenerator write(String name, long value);
/**
* Writes a JSON name/number value pair in the current object context.
* The specified value is written as a JSON number value. The string
* {@code BigDecimal.valueOf(double).toString()}
* is used as the text value for writing.
*
* @param name a name in the JSON name/number pair to be written in
* current JSON object
* @param value a value in the JSON name/number pair to be written in
* current JSON object
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws NumberFormatException if the value is Not-a-Number (NaN) or infinity.
* @throws JsonGenerationException if this method is not called within an
* object context
*/
JsonGenerator write(String name, double value);
/**
* Writes a JSON name/boolean value pair in the current object context.
* If value is true, it writes the JSON {@code true} value, otherwise
* it writes the JSON {@code false} value.
*
* @param name a name in the JSON name/boolean pair to be written in
* current JSON object
* @param value a value in the JSON name/boolean pair to be written in
* current JSON object
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context.
*/
JsonGenerator write(String name, boolean value);
/**
* Writes a JSON name/null value pair in an current object context.
*
* @param name a name in the JSON name/null pair to be written in
* current JSON object
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* object context
*/
JsonGenerator writeNull(String name);
/**
* Writes the end of the current context. If the current context is
* an array context, this method writes the end-of-array character (']').
* If the current context is an object context, this method writes the
* end-of-object character ('}'). After writing the end of the current
* context, the parent context becomes the new current context.
* If parent context is field context, it is closed.
*
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is called in no context.
*/
JsonGenerator writeEnd();
/**
* Writes the specified value as a JSON value within
* the current array, field or root context.
*
* @param value a value to be written in current JSON array
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* array or root context.
*/
JsonGenerator write(JsonValue value);
/**
* Writes the specified value as a JSON string value within
* the current array, field or root context.
*
* @param value a value to be written in current JSON array
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* array or root context.
*/
JsonGenerator write(String value);
/**
* Writes the specified value as a JSON number value within
* the current array, field or root context. The specified value's {@code toString()}
* is used as the the text value for writing.
*
* @param value a value to be written in current JSON array
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* array or root context.
*
* @see javax.json.JsonNumber
*/
JsonGenerator write(BigDecimal value);
/**
* Writes the specified value as a JSON number value within
* the current array, field or root context. The string {@code new BigDecimal(value).toString()}
* is used as the text value for writing.
*
* @param value a value to be written in current JSON array
* @return this generator.
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* array or root context.
*
* @see javax.json.JsonNumber
*/
JsonGenerator write(BigInteger value);
/**
* Writes the specified value as a JSON number value within
* the current array, field or root context. The string {@code new BigDecimal(value).toString()}
* is used as the text value for writing.
*
* @param value a value to be written in current JSON array
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* array or root context.
*/
JsonGenerator write(int value);
/**
* Writes the specified value as a JSON number value within
* the current array, field or root context. The string {@code new BigDecimal(value).toString()}
* is used as the text value for writing.
*
* @param value a value to be written in current JSON array
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* array or root context.
*/
JsonGenerator write(long value);
/**
* Writes the specified value as a JSON number value within the current
* array, field or root context. The string {@code BigDecimal.valueOf(value).toString()}
* is used as the text value for writing.
*
* @param value a value to be written in current JSON array
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* array or root context.
* @throws NumberFormatException if the value is Not-a-Number (NaN) or infinity.
*/
JsonGenerator write(double value);
/**
* Writes a JSON true or false value within the current array, field or root context.
* If value is true, this method writes the JSON {@code true} value,
* otherwise it writes the JSON {@code false} value.
*
* @param value a {@code boolean} value
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* array or root context.
*/
JsonGenerator write(boolean value);
/**
* Writes a JSON null value within the current array, field or root context.
*
* @return this generator
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if this method is not called within an
* array or root context.
*/
JsonGenerator writeNull();
/**
* Closes this generator and frees any resources associated with it.
* This method closes the underlying output source.
*
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
* @throws JsonGenerationException if an incomplete JSON is generated
*/
@Override
void close();
/**
* Flushes the underlying output source. If the generator has saved
* any characters in a buffer, writes them immediately to the underlying
* output source before flushing it.
*
* @throws javax.json.JsonException if an i/o error occurs (IOException
* would be cause of JsonException)
*/
@Override
void flush();
}