com.thoughtworks.xstream.io.json
Class AbstractJsonWriter

java.lang.Object
  extended by com.thoughtworks.xstream.io.AbstractWriter
      extended by com.thoughtworks.xstream.io.json.AbstractJsonWriter
All Implemented Interfaces:
ExtendedHierarchicalStreamWriter, HierarchicalStreamWriter
Direct Known Subclasses:
JsonWriter

public abstract class AbstractJsonWriter
extends AbstractWriter

An abstract implementation of a writer that calls abstract methods to build JSON structures. Note, that XStream's implicit collection feature is only compatible with the syntax in EXPLICIT_MODE.

Since:
1.4
Author:
Jörg Schaible

Nested Class Summary
static class AbstractJsonWriter.Type
           
 
Field Summary
static int DROP_ROOT_MODE
          DROP_ROOT_MODE drops the JSON root node.
static int EXPLICIT_MODE
          EXPLICIT_MODE assures that all data has its explicit equivalent in the resulting JSON.
static int STRICT_MODE
          STRICT_MODE prevents invalid JSON for single value objects when dropping the root.
 
Constructor Summary
AbstractJsonWriter()
          Construct a JSON writer.
AbstractJsonWriter(int mode)
          Construct a JSON writer with a special mode.
AbstractJsonWriter(int mode, NameCoder nameCoder)
          Construct a JSON writer with a special mode and name coder.
AbstractJsonWriter(NameCoder nameCoder)
          Construct a JSON writer with a special name coder.
 
Method Summary
 void addAttribute(String name, String value)
           
protected abstract  void addLabel(String name)
          Add a label to a JSON object.
protected abstract  void addValue(String value, AbstractJsonWriter.Type type)
          Add a value to a JSON object's label or to an array.
protected abstract  void endArray()
          End the JSON array.
 void endNode()
           
protected abstract  void endObject()
          End the JSON object.
protected  AbstractJsonWriter.Type getType(Class clazz)
          Method to return the appropriate JSON type for a Java type.
protected  boolean isArray(Class clazz)
          Method to declare various Java types to be handles as JSON array.
protected abstract  void nextElement()
          Prepare a JSON object or array for another element.
 void setValue(String text)
          Write the value (text content) of the current node.
protected abstract  void startArray()
          Start a JSON array.
 void startNode(String name)
           
 void startNode(String name, Class clazz)
          
protected abstract  void startObject()
          Start a JSON object.
 
Methods inherited from class com.thoughtworks.xstream.io.AbstractWriter
encodeAttribute, encodeNode, underlyingWriter
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.thoughtworks.xstream.io.HierarchicalStreamWriter
close, flush
 

Field Detail

DROP_ROOT_MODE

public static final int DROP_ROOT_MODE
DROP_ROOT_MODE drops the JSON root node.

The root node is the first level of the JSON object i.e.

 { "person": {
     "name": "Joe"
 }}
 
will be written without root simply as
 {
     "name": "Joe"
 }
 
Without a root node, the top level element might now also be an array. However, it is possible to generate invalid JSON unless STRICT_MODE is also set.

Since:
1.3.1
See Also:
Constant Field Values

STRICT_MODE

public static final int STRICT_MODE
STRICT_MODE prevents invalid JSON for single value objects when dropping the root.

The mode is only useful in combination with the DROP_ROOT_MODE. An object with a single value as first node i.e.

 { "name": "Joe" }
 
is simply written as
 "Joe"
 
However, this is no longer valid JSON. Therefore you can activate STRICT_MODE and a ConversionException is thrown instead.

Since:
1.3.1
See Also:
Constant Field Values

EXPLICIT_MODE

public static final int EXPLICIT_MODE
EXPLICIT_MODE assures that all data has its explicit equivalent in the resulting JSON.

XStream is normally using attributes in XML that have no real equivalent in JSON. Additionally it is essential in XML that the individual child elements of a tag keep order and may have the same tag name. XStream's model relies on both characteristics. However, properties of a JSON object do not have a defined order, but their names have to be unique. Only a JSON array defines the order of its elements.

Therefore XStream uses in explicit mode a JSON format that supports the original requirements at the expense of the simplicity of the JSON objects and arrays. Each Java object will be represented by a JSON object with a single property representing the name of the object and an array as value that contains two more arrays. The first one contains a JSON object with all attributes, the second one the value of the Java object which can be null, a string or integer value or again a new JSON object representing a Java object. Here an example of an string array with one member, where the array and the string has an additional attribute 'id':

 {"string-array":[[{"id":"1"}],[{"string":[[{"id":"2"}],["Joe"]]}]]}
 
This format can be used to always deserialize into Java again.

This mode cannot be combined with one of the other modes.

Since:
1.4
See Also:
Constant Field Values
Constructor Detail

AbstractJsonWriter

public AbstractJsonWriter()
Construct a JSON writer.

Since:
1.4

AbstractJsonWriter

public AbstractJsonWriter(int mode)
Construct a JSON writer with a special mode.

Parameters:
mode - a bit mask of the mode constants
Since:
1.4

AbstractJsonWriter

public AbstractJsonWriter(NameCoder nameCoder)
Construct a JSON writer with a special name coder.

Parameters:
nameCoder - the name coder to use
Since:
1.4

AbstractJsonWriter

public AbstractJsonWriter(int mode,
                          NameCoder nameCoder)
Construct a JSON writer with a special mode and name coder.

Parameters:
mode - a bit mask of the mode constants
nameCoder - the name coder to use
Since:
1.4
Method Detail

startNode

public void startNode(String name,
                      Class clazz)
Description copied from class: AbstractWriter

Specified by:
startNode in interface ExtendedHierarchicalStreamWriter
Overrides:
startNode in class AbstractWriter

startNode

public void startNode(String name)

addAttribute

public void addAttribute(String name,
                         String value)

setValue

public void setValue(String text)
Description copied from interface: HierarchicalStreamWriter
Write the value (text content) of the current node.


endNode

public void endNode()

getType

protected AbstractJsonWriter.Type getType(Class clazz)
Method to return the appropriate JSON type for a Java type.

Parameters:
clazz - the type
Returns:
One of the AbstractJsonWriter.Type instances
Since:
1.4.4

isArray

protected boolean isArray(Class clazz)
Method to declare various Java types to be handles as JSON array.

Parameters:
clazz - the type
Returns:
true if handles as array
Since:
1.4

startObject

protected abstract void startObject()
Start a JSON object.

Since:
1.4

addLabel

protected abstract void addLabel(String name)
Add a label to a JSON object.

Parameters:
name - the label's name
Since:
1.4

addValue

protected abstract void addValue(String value,
                                 AbstractJsonWriter.Type type)
Add a value to a JSON object's label or to an array.

Parameters:
value - the value itself
type - the JSON type
Since:
1.4

startArray

protected abstract void startArray()
Start a JSON array.

Since:
1.4

nextElement

protected abstract void nextElement()
Prepare a JSON object or array for another element.

Since:
1.4

endArray

protected abstract void endArray()
End the JSON array.

Since:
1.4

endObject

protected abstract void endObject()
End the JSON object.

Since:
1.4


Copyright © 2004-2014 XStream. All Rights Reserved.