org.elkoserver.json
Class JSONLiteral

java.lang.Object
  org.elkoserver.json.JSONLiteral

public class JSONLiteral
extends Object

A literal JSON string, representing either a message or an object, undergoing incremental construction. Users of this class should call one of the constructors to begin creation of the literal, incrementally add to it using the various addParameter() methods, then finally complete it by calling the finish() method. After the literal is completed, it may be used as another literal's parameter value, or its string form can be extracted by calling sendableString().

Constructor Summary

JSONLiteral()
Begin a new literal that will be filled in incrementally.

JSONLiteral(EncodeControl control)
Begin a new literal that will be filled in incrementally.

JSONLiteral(Referenceable target, String verb)
Begin a new literal representing a JSON message.

JSONLiteral(String type, EncodeControl control)
Begin a new literal representing a JSON object.

JSONLiteral(String target, String verb)
Begin a new literal representing a JSON message.

Method Summary

void	addParameter(String param, boolean value) Add a boolean parameter to an incomplete literal.
void	addParameter(String param, boolean[] value) Add a boolean array parameter to an incomplete literal.
void	addParameter(String param, Collection value) Add a collection parameter to an incomplete literal (as an array).
void	addParameter(String param, double value) Add a floating point parameter to an incomplete literal.
void	addParameter(String param, double[] value) Add a double array parameter to an incomplete literal.
void	addParameter(String param, Encodable value) Add an object-valued parameter to an incomplete literal.
void	addParameter(String param, int value) Add an integer parameter to an incomplete literal.
void	addParameter(String param, int[] value) Add an int array parameter to an incomplete literal.
void	addParameter(String param, JSONArray value) Add a JSONArray parameter to an incomplete literal.
void	addParameter(String param, JSONLiteralArray value) Add an array literal parameter to an incomplete literal.
void	addParameter(String param, JSONObject value) Add a JSON object parameter to an incomplete literal.
void	addParameter(String param, long value) Add a long parameter to an incomplete literal.
void	addParameter(String param, long[] value) Add a long array parameter to an incomplete literal.
void	addParameter(String param, Object value) Add an arbitrary parameter to an incomplete literal.
void	addParameter(String param, Object[] value) Add an array parameter to an incomplete literal.
void	addParameter(String param, Referenceable value) Add a reference parameter to an incomplete literal.
void	addParameter(String param, String value) Add a string parameter to an incomplete literal.
void	addParameterOpt(String param, boolean[] value) Add an optional boolean array parameter to an incomplete literal.
void	addParameterOpt(String param, Collection value) Add an optional collection parameter to an incomplete literal.
void	addParameterOpt(String param, double[] value) Add an optional double array parameter to an incomplete literal.
void	addParameterOpt(String param, Encodable value) Add an optional object-valued parameter to an incomplete literal.
void	addParameterOpt(String param, int[] value) Add an optional int array parameter to an incomplete literal.
void	addParameterOpt(String param, JSONArray value) Add an optional JSONArray parameter to an incomplete literal.
void	addParameterOpt(String param, JSONLiteralArray value) Add an optional array literal parameter to an incomplete literal.
void	addParameterOpt(String param, JSONObject value) Add an optional JSON object parameter to an incomplete literal.
void	addParameterOpt(String param, long[] value) Add an optional long array parameter to an incomplete literal.
void	addParameterOpt(String param, Object value) Add an optional arbitrary parameter to an incomplete literal.
void	addParameterOpt(String param, Object[] value) Add an optional array parameter to an incomplete literal.
void	addParameterOpt(String param, Referenceable value) Add an optional reference parameter to an incomplete literal.
void	addParameterOpt(String param, String value) Add an optional string parameter to an incomplete literal.
void	addParameterRef(String param, JSONLiteralArray value) Add a dereferenceable array literal parameter to an incomplete literal.
void	addParameterRef(String param, Object[] value) Add a dereferenceable array parameter to an incomplete literal.
void	addParameterRef(String param, Referenceable value) Add a dereferenceable reference parameter to an incomplete literal.
void	finish() Finish construction of the literal.
int	length() Obtain the number of characters in the literal.
String	sendableString() Obtain a string representation of this literal suitable for output to a connection.
static void	setStrictness(boolean flag) Set the global strictness flag.
String	toString() Obtain a printable string representation of this literal, in whatever its current state is.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JSONLiteral

public JSONLiteral(EncodeControl control)

Begin a new literal that will be filled in incrementally.

Parameters:

control - Encode control determining what flavor of encoding is being done.

JSONLiteral

public JSONLiteral()

Begin a new literal that will be filled in incrementally.

JSONLiteral

public JSONLiteral(Referenceable target,
                   String verb)

Begin a new literal representing a JSON message.

Parameters:

target - The target to whom this message is addressed.

verb - The message verb.

JSONLiteral

public JSONLiteral(String target,
                   String verb)

Begin a new literal representing a JSON message.

Parameters:

target - The reference string of the target to whom this message is addressed.

verb - The message verb.

JSONLiteral

public JSONLiteral(String type,
                   EncodeControl control)

Begin a new literal representing a JSON object.

Parameters:

type - The type tag of this object.

control - Encode control determining what flavor of encoding is being done.

Method Detail

addParameter

public void addParameter(String param,
                         Object value)

Add an arbitrary parameter to an incomplete literal. Note that any parameter value whose string representation encodes to null will be ignored (i.e., not added to the literal).

Parameters:

param - The parameter name.

value - The parameter value.

Throws:

Error - if you try to add a parameter to literal that is already complete.

addParameterOpt

public void addParameterOpt(String param,
                            Object value)

Add an optional arbitrary parameter to an incomplete literal. This is similar to addParameter(String,Object), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The optional parameter value.

addParameter

public void addParameter(String param,
                         Object[] value)

Add an array parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The (array) parameter value.

addParameter

public void addParameter(String param,
                         Collection value)

Add a collection parameter to an incomplete literal (as an array).

Parameters:

param - The parameter name.

value - The (collection) parameter value.

addParameterRef

public void addParameterRef(String param,
                            Object[] value)

Add a dereferenceable array parameter to an incomplete literal. Object references encoded in this way will be decoded as pointers to the referenced objects rather than as the object reference strings themselves.

Parameters:

param - The parameter name.

value - The (array of Referenceable) parameter value.

addParameterOpt

public void addParameterOpt(String param,
                            Object[] value)

Add an optional array parameter to an incomplete literal. This is similar to addParameter(String,Object[]), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The optional (array) parameter value.

addParameterOpt

public void addParameterOpt(String param,
                            Collection value)

Add an optional collection parameter to an incomplete literal. This is similar to addParameter(String,Collection), except that if the value is null or the collection is empty, the parameter is not added.

Parameters:

param - The parameter name.

value - The optional (collection) parameter value.

addParameter

public void addParameter(String param,
                         int[] value)

Add an int array parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The parameter (int array) value.

addParameterOpt

public void addParameterOpt(String param,
                            int[] value)

Add an optional int array parameter to an incomplete literal. This is similar to addParameter(String,int[]), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name

value - The optional (int array) parameter value

addParameter

public void addParameter(String param,
                         long[] value)

Add a long array parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The parameter (long array) value.

addParameterOpt

public void addParameterOpt(String param,
                            long[] value)

Add an optional long array parameter to an incomplete literal. This is similar to addParameter(String,long[]), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The optional (long array) parameter value.

addParameter

public void addParameter(String param,
                         double[] value)

Add a double array parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The parameter (double array) value.

addParameterOpt

public void addParameterOpt(String param,
                            double[] value)

Add an optional double array parameter to an incomplete literal. This is similar to addParameter(String,double[]), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The optional (double array) parameter value.

addParameter

public void addParameter(String param,
                         boolean[] value)

Add a boolean array parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The parameter (boolean array) value.

addParameterOpt

public void addParameterOpt(String param,
                            boolean[] value)

Add an optional boolean array parameter to an incomplete literal. This is similar to addParameter(String,boolean[]), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The optional (boolean array) parameter value.

addParameter

public void addParameter(String param,
                         JSONArray value)

Add a JSONArray parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The parameter (JSONArray) value.

addParameterOpt

public void addParameterOpt(String param,
                            JSONArray value)

Add an optional JSONArray parameter to an incomplete literal. This is similar to addParameter(String,JSONArray), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The optional (JSONArray) parameter value.

addParameter

public void addParameter(String param,
                         JSONLiteralArray value)

Add an array literal parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The (JSONLiteralArray) parameter value.

addParameterOpt

public void addParameterOpt(String param,
                            JSONLiteralArray value)

Add an optional array literal parameter to an incomplete literal. This is similar to addParameter(String,JSONLiteralArray), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The optional (JSONLiteralArray) parameter value

addParameterRef

public void addParameterRef(String param,
                            JSONLiteralArray value)

Add a dereferenceable array literal parameter to an incomplete literal. The array being encoded should contain a collection of object reference strings; these reference strings will be decoded as pointers to the referenced objects, rather than as the reference strings themselves.

Parameters:

param - The parameter name.

value - The (JSONLiteralArray) parameter value.

addParameter

public void addParameter(String param,
                         Encodable value)

Add an object-valued parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The (Encodable) parameter value.

addParameterOpt

public void addParameterOpt(String param,
                            Encodable value)

Add an optional object-valued parameter to an incomplete literal. This is similar to addParameter(String,Encodable), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The optional (Encodable) parameter value.

addParameter

public void addParameter(String param,
                         double value)

Add a floating point parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The (double) parameter value.

addParameter

public void addParameter(String param,
                         boolean value)

Add a boolean parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The (boolean) parameter value.

addParameter

public void addParameter(String param,
                         int value)

Add an integer parameter to an incomplete literal.

Parameters:

param - The parameter name

value - The (int) parameter value.

addParameter

public void addParameter(String param,
                         long value)

Add a long parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The (long) parameter value.

addParameter

public void addParameter(String param,
                         JSONObject value)

Add a JSON object parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The (JSONObject) parameter value.

addParameterOpt

public void addParameterOpt(String param,
                            JSONObject value)

Add an optional JSON object parameter to an incomplete literal. This is similar to addParameter(String,JSONObject), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The (JSONObject) parameter value.

addParameter

public void addParameter(String param,
                         Referenceable value)

Add a reference parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The (Referenceable) parameter value.

addParameterOpt

public void addParameterOpt(String param,
                            Referenceable value)

Add an optional reference parameter to an incomplete literal. This is similar to addParameter(String,Referenceable), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name

value - The parameter value

addParameterRef

public void addParameterRef(String param,
                            Referenceable value)

Add a dereferenceable reference parameter to an incomplete literal. The object reference encoded in this way will be decoded as a poniter to the referenced object rather than as the object reference string itself.

Parameters:

param - The parameter name.

value - The (Referenceable) parameter value

addParameter

public void addParameter(String param,
                         String value)

Add a string parameter to an incomplete literal.

Parameters:

param - The parameter name.

value - The (String) parameter value.

addParameterOpt

public void addParameterOpt(String param,
                            String value)

Add an optional string parameter to an incomplete literal. This is similar to addParameter(String,String), except that if the value is null, the parameter is not added.

Parameters:

param - The parameter name.

value - The parameter value.

finish

public void finish()

Finish construction of the literal.

Throws:

Error - if you try to finish a literal that is already complete.

length

public int length()

Obtain the number of characters in the literal.

Returns:

the number of characters currently in this literal.

sendableString

public String sendableString()

Obtain a string representation of this literal suitable for output to a connection.

Returns:

a sendable string representation of this literal.

Throws:

Error - if the literal is not finished.

toString

public String toString()

Obtain a printable string representation of this literal, in whatever its current state is.

Overrides:

toString in class Object

Returns:

a printable representation of this literal.

setStrictness

public static void setStrictness(boolean flag)

Set the global strictness flag. This controls whether interpretation of the JSON standard will be strict or not (by default, it is strict). The principal impact of this is that when being strict, property names are output as strings rather than as keywords. This is safer for browsers, but much harder on the eyes when debugging.

Parameters:

flag - If true, adhere strictly to the JSON standard; if false, be prettier and friendlier.