Package com.cedarsoftware.io

Interface WriterContext

All Known Implementing Classes:

JsonWriter

public interface WriterContext

Author:

Kenny Partlow ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

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.

Method Summary

Modifier and Type	Method	Description
Map<Object,Long>	getObjsReferenced()	Provide access to all objects that are referenced
WriteOptions	getWriteOptions()	Gets the write options for the current serialization
void	writeArrayFieldStart(String name)	Writes a complete JSON array field start with automatic comma handling.
void	writeBooleanField(String name, boolean value)	Writes a complete JSON boolean field with automatic comma handling.
void	writeEndArray()	Writes a JSON array closing bracket ].
void	writeEndObject()	Writes a JSON object closing brace "}".
void	writeFieldName(String name)	Writes a JSON field name followed by a colon.
void	writeImpl(Object obj, boolean showType)	Write any object fully.
void	writeNumberField(String name, Number value)	Writes a complete JSON number field with automatic comma handling.
void	writeObject(Object obj, boolean showType, boolean bodyOnly)	Allows you to use the current JsonWriter to write an object out.
void	writeObjectField(String name, Object value)	Writes a complete JSON object field with automatic serialization and comma handling.
void	writeObjectFieldStart(String name)	Writes a complete JSON object field start with automatic comma handling.
void	writeStartArray()	Writes a JSON array opening bracket [.
void	writeStartObject()	Writes a JSON object opening brace "{".
void	writeStringField(String name, String value)	Writes a complete JSON string field with automatic comma handling.
void	writeValue(Object value)	Writes a JSON value by serializing the given object.
void	writeValue(String value)	Writes a JSON string value with proper quote escaping.

Method Details

getWriteOptions

WriteOptions getWriteOptions()

Gets the write options for the current serialization

Returns:

WriteOptions

writeObject

void writeObject(Object obj,
 boolean showType,
 boolean bodyOnly)
          throws IOException

Allows you to use the current JsonWriter to write an object out.

Throws:

IOException

writeImpl

void writeImpl(Object obj,
 boolean showType)
        throws IOException

Write any object fully.

Throws:

IOException

getObjsReferenced

Map<Object,Long> getObjsReferenced()

Provide access to all objects that are referenced

writeFieldName

void writeFieldName(String name)
             throws IOException

Writes a JSON field name followed by a colon. This method handles quote escaping and proper JSON formatting automatically.

Example: writeFieldName("name") produces "name":

Important: This method does NOT write a preceding comma. If you need a comma before the field (for non-first fields in an object), you must write it manually. Consider using the higher-level methods like writeStringField(String, String) or writeObjectField(String, Object) which handle commas automatically.

Parameters:

name - the field name to write (without quotes)

Throws:

IOException - if an I/O error occurs

writeStringField

void writeStringField(String name,
 String value)
               throws IOException

Writes a complete JSON string field with automatic comma handling.

Example: writeStringField("name", "John") produces ,"name":"John"

This method automatically:

• Writes a preceding comma (for proper JSON object formatting)
• Escapes special characters in both field name and value
• Handles null values by writing ,"name":null

Usage in custom writers:

 public void write(Object obj, boolean showType, Writer output, WriterContext context) {
     MyClass instance = (MyClass) obj;
     output.write('{');
     context.writeStringField("firstName", instance.getFirstName());
     context.writeStringField("lastName", instance.getLastName());
     output.write('}');
 }
 

Parameters:

name - the field name

value - the string value (may be null)

Throws:

IOException - if an I/O error occurs

writeObjectField

void writeObjectField(String name,
 Object value)
               throws IOException

Writes a complete JSON object field with automatic serialization and comma handling.

Example: writeObjectField("address", addressObj) produces ,"address":{...} where the address object is fully serialized according to json-io's rules.

This method automatically:

• Writes a preceding comma (for proper JSON object formatting)
• Serializes the value object with proper type information and reference tracking
• Handles null values by writing ,"name":null
• Handles circular references and object deduplication

Usage in custom writers:

 public void write(Object obj, boolean showType, Writer output, WriterContext context) {
     MyClass instance = (MyClass) obj;
     output.write('{');
     context.writeObjectField("config", instance.getConfig());
     context.writeObjectField("data", instance.getData());
     output.write('}');
 }
 

Parameters:

name - the field name

value - the object to serialize (may be null)

Throws:

IOException - if an I/O error occurs

writeStartObject

void writeStartObject()
               throws IOException

Writes a JSON object opening brace "{".

This should be paired with writeEndObject() to properly close the object.

Usage pattern:

 context.writeStartObject();
 context.writeStringField("name", "value");
 context.writeEndObject();
 

Throws:

IOException - if an I/O error occurs

See Also:

• writeEndObject()

writeEndObject

void writeEndObject()
             throws IOException

Writes a JSON object closing brace "}".

This should be paired with a preceding writeStartObject() call.

Throws:

IOException - if an I/O error occurs

See Also:

• writeStartObject()

writeStartArray

void writeStartArray()
              throws IOException

Writes a JSON array opening bracket [.

This should be paired with writeEndArray() to properly close the array.

Usage pattern:

 context.writeStartArray();
 for (Item item : items) {
     context.writeStartObject();
     context.writeObjectField("data", item);
     context.writeEndObject();
 }
 context.writeEndArray();
 

Throws:

IOException - if an I/O error occurs

See Also:

• writeEndArray()

writeEndArray

void writeEndArray()
            throws IOException

Writes a JSON array closing bracket ].

This should be paired with a preceding writeStartArray() call.

Throws:

IOException - if an I/O error occurs

See Also:

• writeStartArray()

writeValue

void writeValue(String value)
         throws IOException

Writes a JSON string value with proper quote escaping.

Example: writeValue("Hello") produces "Hello"

This method:

• Writes opening quote
• Escapes special characters (quotes, backslashes, control characters)
• Writes closing quote
• Handles null by writing null (without quotes)

Usage pattern:

 context.writeFieldName("name");
 context.writeValue("John Doe");
 // Produces: "name":"John Doe"
 

Parameters:

value - the string value to write (may be null)

Throws:

IOException - if an I/O error occurs

writeValue

void writeValue(Object value)
         throws IOException

Writes a JSON value by serializing the given object.

Example: writeValue(myObject) produces the full JSON representation of myObject

This method:

• Serializes the object with proper type information and reference tracking
• Handles null by writing null
• Handles primitives, strings, collections, maps, and custom objects
• Handles circular references and object deduplication

Usage pattern:

 context.writeFieldName("config");
 context.writeValue(configObject);
 // Produces: "config":{...serialized config...}
 

Parameters:

value - the object to serialize (may be null)

Throws:

IOException - if an I/O error occurs

writeArrayFieldStart

void writeArrayFieldStart(String name)
                   throws IOException

Writes a complete JSON array field start with automatic comma handling.

Example: writeArrayFieldStart("items") produces ,"items":[

This is a convenience method that combines three operations:

• Writes a leading comma (for proper JSON object formatting)
• Writes the field name with quotes and colon
• Writes the array opening bracket

Usage pattern:

 context.writeArrayFieldStart("entries");
 for (Entry entry : entries) {
     // Write array elements...
 }
 context.writeEndArray();
 // Produces: ,"entries":[...array elements...]
 

This method writes a LEADING comma, making it suitable for fields after the first field.

Parameters:

name - the field name

Throws:

IOException - if an I/O error occurs

writeObjectFieldStart

void writeObjectFieldStart(String name)
                    throws IOException

Writes a complete JSON object field start with automatic comma handling.

Example: writeObjectFieldStart("config") produces ,"config":{

This is a convenience method that combines three operations:

• Writes a leading comma (for proper JSON object formatting)
• Writes the field name with quotes and colon
• Writes the object opening brace

Usage pattern:

 context.writeObjectFieldStart("metadata");
 context.writeStringField("version", "1.0");
 context.writeNumberField("count", 42);
 context.writeEndObject();
 // Produces: ,"metadata":{"version":"1.0","count":42}
 

This method writes a LEADING comma, making it suitable for fields after the first field.

Parameters:

name - the field name

Throws:

IOException - if an I/O error occurs

writeNumberField

void writeNumberField(String name,
 Number value)
               throws IOException

Writes a complete JSON number field with automatic comma handling.

Example: writeNumberField("count", 42) produces ,"count":42

This method automatically:

• Writes a preceding comma (for proper JSON object formatting)
• Escapes the field name
• Writes the number value WITHOUT quotes (proper JSON number format)
• Handles null values by writing ,"name":null

Usage pattern:

 context.writeNumberField("capacity", 16);
 context.writeNumberField("loadFactor", 0.75f);
 context.writeNumberField("size", 100L);
 // Produces: ,"capacity":16,"loadFactor":0.75,"size":100
 

This method writes a LEADING comma, making it suitable for fields after the first field.

Parameters:

name - the field name

value - the number value (may be null)

Throws:

IOException - if an I/O error occurs

writeBooleanField

void writeBooleanField(String name,
 boolean value)
                throws IOException

Writes a complete JSON boolean field with automatic comma handling.

Example: writeBooleanField("active", true) produces ,"active":true

This method automatically:

• Writes a preceding comma (for proper JSON object formatting)
• Escapes the field name
• Writes the boolean value WITHOUT quotes (proper JSON boolean format)

Usage pattern:

 context.writeBooleanField("caseSensitive", true);
 context.writeBooleanField("enabled", false);
 // Produces: ,"caseSensitive":true,"enabled":false
 

This method writes a LEADING comma, making it suitable for fields after the first field.

Parameters:

name - the field name

value - the boolean value

Throws:

IOException - if an I/O error occurs