org.kopitubruk.util.json
Class JSONConfig

java.lang.Object
  org.kopitubruk.util.json.JSONConfig

All Implemented Interfaces:

Serializable, Cloneable

public class JSONConfig
extends Object
implements Serializable, Cloneable

A configuration object for JSONUtil to control various encoding options.

It is possible to change the defaults by using the JSONConfigDefaults class. See that class for details.

These are the names of the boolean flags and their normal defaults if you don't change them. See the setters for these for descriptions of what they do.

Validation related options.

• validatePropertyNames = true
• detectDataStructureLoops = true
• escapeBadIdentifierCodePoints = false
• fullJSONIdentifierCodePoints = false
• fastStrings = false

Safe alternate encoding options.

• encodeNumericStringsAsNumbers = false
• escapeNonAscii = false
• unEscapeWherePossible = false
• escapeSurrogates = false
• passThroughEscapes = false
• encodeDatesAsStrings = false
• reflectUnknownObjects = false
• preciseNumbers = false
• smallNumbers = false
• usePrimitiveArrays = false
• cacheReflectionData = false

Allow generation of certain types of non-standard JSON.

These could cause problems for some things that take JSON. Defaults are for standard JSON. Be careful about changing these. They should work fine if the JSON is interpreted by a standard Javascript eval(), except ECMAScript 6 code points if your interpreter doesn't support those. Going non-default on any of these tends not to work in strict JSON parsers such as JQuery.

• quoteIdentifier = true
• useECMA6 = false
• allowReservedWordsInIdentifiers = false
• encodeDatesAsObjects = false

You can change the locale being used for error messages and log messages and possibly by JSONAble objects for encoding.

You can create number formats associated with specific numeric types if you want your numbers encoded in a certain way.

If you've enabled special date handling options, you can change the way date strings are generated and the way that they are parsed.

This class also keeps track of classes which will be automatically reflected when encountered.

This class NOT thread safe. There are issues with the loop detection logic and any custom number or date formats used. Never share objects of this class between threads.

Author:

Bill Davidson

See Also:

JSONConfigDefaults, Serialized Form

Field Summary

static int	DISCARD Discard bad data.
static int	ESCAPE Escape bad data.
static int	EXCEPTION Throw an exception on bad data.
static int	PASS Pass bad data through.
static int	REPLACE Replace bad data with the Unicode replacement character U+FFFD.

Constructor Summary

JSONConfig()
Create a JSONConfig

JSONConfig(Locale locale)
Create a JSONConfig with the given locale.

Method Summary

JSONConfig	addDateParseFormat(DateFormat fmt) Add a date parsing format to the list of parsing formats.
DateFormat	addDateParseFormat(String fmtStr) Add a date parsing format to the list of parsing formats.
JSONConfig	addDateParseFormats(Collection<? extends DateFormat> fmts) Add a collection of date parsing formats to the list of date parsing formats.
JSONConfig	addNumberFormat(Class<? extends Number> numericClass, NumberFormat fmt) Add a number format for a particular type that extends Number.
JSONConfig	addNumberFormat(Number numericType, NumberFormat fmt) Add a number format for a particular type that extends Number.
JSONConfig	addNumberFormats(Map<Class<? extends Number>,NumberFormat> numFmtMap) Add a map of number formats to the current map of number formats.
JSONConfig	addReflectClass(Object obj) Add the class of the given object to the set of classes that automatically get reflected.
JSONConfig	addReflectClassByName(String className) Add the given class to the set of classes to be reflected.
JSONConfig	addReflectClasses(Collection<?> classes) Add the classes of all of the given objests to the list of classes that automatically get reflected.
JSONConfig	clearDateGenFormat() Clear date generation format.
JSONConfig	clearDateParseFormats() Clear any date parse formats.
JSONConfig	clearNumberFormats() Clear all number formats.
JSONConfig	clearReflectClasses() Clear all reflection classes, disabling all automatic reflection.
JSONConfig	clone() Return a clone of this object.
IndentPadding	getIndentPadding() Get the padding object.
Locale	getLocale() Get the locale for this instance.
NumberFormat	getNumberFormat(Class<? extends Number> numericClass) Get the number format for the given class.
NumberFormat	getNumberFormat(Number num) Get the number format for the class of the given numeric type.
JSONReflectedClass	getReflectedClass(Object obj) Get the JSONReflectedClass for the given object if it is stored.
int	getReflectionPrivacy() Get the reflection privacy level.
int	getUndefinedCodePointPolicy() Get the policy for undefined code points.
int	getUnmatchedSurrogatePolicy() Get the policy for unmatched surrogates.
boolean	isAllowReservedWordsInIdentifiers() Get the allowReservedWordsInIdentifiers policy.
boolean	isCacheReflectionData() Get the the cacheReflectionData policy.
boolean	isDetectDataStructureLoops() Return true if data structure loops will be detected.
boolean	isEncodeDatesAsObjects() Get the encode dates policy.
boolean	isEncodeDatesAsStrings() Get the encode dates as strings policy.
boolean	isEncodeNumericStringsAsNumbers() If true, then strings will be checked for number patterns and if they look like numbers, then they won't be quoted.
boolean	isEscapeBadIdentifierCodePoints() Find out if bad identifier code points will be escaped.
boolean	isEscapeNonAscii() Check if non-ascii characters are to be encoded as Unicode escapes.
boolean	isEscapeSurrogates() Return the escape surrogates policy.
boolean	isFastStrings() Get the fastStrings policy.
boolean	isFormatDates() Find out if special date formatting is enabled.
boolean	isFullJSONIdentifierCodePoints() Get the full JSON identifier code points policy.
boolean	isPassThroughEscapes() Get the pass through escapes policy.
boolean	isPreciseNumbers() Get the preciseNumbers policy.
boolean	isQuoteIdentifier() Find out what the identifier quote policy is.
boolean	isReflectClass(Object obj) Return true if the given class is in the set of classes being automatically reflected.
boolean	isReflectUnknownObjects() Get the reflection of unknown objects policy.
boolean	isSmallNumbers() Get the smallNumbers policy.
boolean	isUnEscapeWherePossible() The unEscape policy.
boolean	isUseECMA6() Find out if ECMAScript 6 code point escapes are enabled.
boolean	isUsePrimitiveArrays() The primitive arrays policy.
boolean	isValidatePropertyNames() Check if property names will be validated.
JSONConfig	removeNumberFormat(Class<? extends Number> numericClass) Remove the requested class from the number formats that this config knows about.
JSONConfig	removeNumberFormat(Number num) Remove the requested class from the number formats that this config knows about.
JSONConfig	removeReflectClass(Object obj) Remove the given class from the list of automatically reflected classes.
JSONConfig	removeReflectClasses(Collection<?> classes) Remove the given classes from the list of automatically reflected classes.
JSONConfig	setAllowReservedWordsInIdentifiers(boolean allowReservedWordsInIdentifiers) If true then reserved words will be allowed in identifiers even when identifier validation is enabled.
JSONConfig	setBadCharacterPolicy(int badCharacterPolicy) Convenience method to call both setUnmatchedSurrogatePolicy(int) and setUndefinedCodePointPolicy(int) using the same value.
JSONConfig	setCacheReflectionData(boolean cacheReflectionData) If true, then when an object is reflected its reflection data will be cached to improve performance on subsequent reflections of objects of its class.
JSONConfig	setDateGenFormat(DateFormat fmt) Set the date string generation format used when encodeDatesAsStrings or encodeDatesAsObjects are true.
DateFormat	setDateGenFormat(String fmtStr) Set the date string generation format.
JSONConfig	setDetectDataStructureLoops(boolean detectDataStructureLoops) Enable or disable data structure loop detection.
JSONConfig	setEncodeDatesAsObjects(boolean encodeDatesAsObjects) If true, then Date objects will be encoded as Javascript dates, using new Date(dateString).
JSONConfig	setEncodeDatesAsStrings(boolean encodeDatesAsStrings) If true, then Date objects will be encoded as ISO 8601 date strings or a custom date format if you have called setDateGenFormat(DateFormat).
JSONConfig	setEncodeNumericStringsAsNumbers(boolean encodeNumericStringsAsNumbers) If true, then strings will be checked for number patterns and if they look like numbers, then they won't be quoted.
JSONConfig	setEscapeBadIdentifierCodePoints(boolean escapeBadIdentifierCodePoints) If true, then any bad code points in identifiers will be escaped.
JSONConfig	setEscapeNonAscii(boolean escapeNonAscii) If you want non-ascii characters encoded as Unicode escapes in strings and identifiers, you can do that by setting this to true.
JSONConfig	setEscapeSurrogates(boolean escapeSurrogates) If true then all surrogates will be escaped in strings and identifiers and escapeNonAscii will be forced to false.
JSONConfig	setFastStrings(boolean fastStrings) If true, then string values will be copied to the output with no escaping or validation.
JSONConfig	setFullJSONIdentifierCodePoints(boolean fullJSONIdentifierCodePoints) If true, then the full set of identifier code points permitted by the JSON standard will be allowed instead of the more restrictive set permitted by the ECMAScript standard.
JSONConfig	setIndentPadding(IndentPadding indentPadding) Set the padding object.
JSONConfig	setLocale(Locale locale) Set the locale.
JSONConfig	setPassThroughEscapes(boolean passThroughEscapes) If true, then legal escapes in strings will be passed through unchanged.
JSONConfig	setPreciseNumbers(boolean preciseNumbers) If true then integer numbers which are not exactly representable by a 64 bit double precision floating point number will be quoted in the output.
JSONConfig	setQuoteIdentifier(boolean quoteIdentifier) Control whether identifiers are quoted or not.
JSONConfig	setReflectionPrivacy(int reflectionPrivacy) Set the privacy level for reflection.
JSONConfig	setReflectUnknownObjects(boolean reflectUnknownObjects) Set the unknown object reflection encoding policy.
JSONConfig	setSmallNumbers(boolean smallNumbers) If true then JSONParser will attempt to minimize the storage used for all numbers.
JSONConfig	setUndefinedCodePointPolicy(int undefinedCodePointPolicy) Tell JSONUtil what to do when it encounters undefined code points in strings and identifiers.
JSONConfig	setUnEscapeWherePossible(boolean unEscapeWherePossible) If true then where possible, undo inline escapes in strings before going through normal string processing.
JSONConfig	setUnmatchedSurrogatePolicy(int unmatchedSurrogatePolicy) Tell JSONUtil what to do when it encounters unmatched surrogates in strings and identifiers.
JSONConfig	setUseECMA6(boolean useECMA6) If you set this to true, then when JSONUtil generates Unicode escapes, it will use ECMAScript 6 code point escapes if they are shorter than code unit escapes.
JSONConfig	setUsePrimitiveArrays(boolean usePrimitiveArrays) If true, then when JSONParser encounters a JSON array of non-null wrappers of primitives and those primitives are all compatible with each other, then instead of an ArrayList of wrappers for those primitives it will create an array of those primitives in order to save memory.
JSONConfig	setValidatePropertyNames(boolean validatePropertyNames) If true, then property names will be validated.

Methods inherited from class java.lang.Object

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

Field Detail

REPLACE

public static final int REPLACE

Replace bad data with the Unicode replacement character U+FFFD. Value 0.

See Also:

setUnmatchedSurrogatePolicy(int), setUndefinedCodePointPolicy(int), setBadCharacterPolicy(int), JSONConfigDefaults.setUnmatchedSurrogatePolicy(int), JSONConfigDefaults.setUndefinedCodePointPolicy(int), JSONConfigDefaults.setBadCharacterPolicy(int), Constant Field Values

DISCARD

public static final int DISCARD

Discard bad data. Value 1.

See Also:

setUnmatchedSurrogatePolicy(int), setUndefinedCodePointPolicy(int), setBadCharacterPolicy(int), JSONConfigDefaults.setUnmatchedSurrogatePolicy(int), JSONConfigDefaults.setUndefinedCodePointPolicy(int), JSONConfigDefaults.setBadCharacterPolicy(int), Constant Field Values

EXCEPTION

public static final int EXCEPTION

Throw an exception on bad data. Value 2.

See Also:

setUnmatchedSurrogatePolicy(int), setUndefinedCodePointPolicy(int), setBadCharacterPolicy(int), JSONConfigDefaults.setUnmatchedSurrogatePolicy(int), JSONConfigDefaults.setUndefinedCodePointPolicy(int), JSONConfigDefaults.setBadCharacterPolicy(int), Constant Field Values

ESCAPE

public static final int ESCAPE

Escape bad data. Value 3.

See Also:

setUnmatchedSurrogatePolicy(int), setUndefinedCodePointPolicy(int), setBadCharacterPolicy(int), JSONConfigDefaults.setUnmatchedSurrogatePolicy(int), JSONConfigDefaults.setUndefinedCodePointPolicy(int), JSONConfigDefaults.setBadCharacterPolicy(int), Constant Field Values

PASS

public static final int PASS

Pass bad data through. Value 4.

See Also:

setUnmatchedSurrogatePolicy(int), setUndefinedCodePointPolicy(int), setBadCharacterPolicy(int), JSONConfigDefaults.setUnmatchedSurrogatePolicy(int), JSONConfigDefaults.setUndefinedCodePointPolicy(int), JSONConfigDefaults.setBadCharacterPolicy(int), Constant Field Values

Constructor Detail

JSONConfig

public JSONConfig()

Create a JSONConfig

JSONConfig

public JSONConfig(Locale locale)

Create a JSONConfig with the given locale.

Parameters:

locale - the locale to set.

Method Detail

clone

public JSONConfig clone()

Return a clone of this object. Note that this is unsynchronized, so code accordingly. This is a deep clone so any date or number formats or reflect classes defined for this instance will also be cloned.

Overrides:

clone in class Object

Returns:

a clone of this object.

getLocale

public Locale getLocale()

Get the locale for this instance.

Returns:

the locale

See Also:

JSONConfigDefaults.getLocale()

setLocale

public JSONConfig setLocale(Locale locale)

Set the locale. This can be used for error messages or JSONAble's that can use a locale.

Parameters:

locale - the locale to set

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setLocale(Locale)

getNumberFormat

public NumberFormat getNumberFormat(Class<? extends Number> numericClass)

Get the number format for the given class.

Parameters:

numericClass - A class.

Returns:

A number format or null if one has not been set.

See Also:

JSONConfigDefaults.getNumberFormat(Class)

getNumberFormat

public NumberFormat getNumberFormat(Number num)

Get the number format for the class of the given numeric type.

Parameters:

num - An object that implements Number.

Returns:

A number format or null if one has not been set.

See Also:

JSONConfigDefaults.getNumberFormat(Number)

addNumberFormat

public JSONConfig addNumberFormat(Class<? extends Number> numericClass,
                                  NumberFormat fmt)

Add a number format for a particular type that extends Number. You can set one format per type that extends Number. All JSON conversions that use this config will use the given format for output of numbers of the given class.

This could allow you to limit the number of digits printed for a float or a double for example, getting rid of excess digits caused by rounding problems in floating point numbers.

Parameters:

numericClass - The class.

fmt - The number format.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.addNumberFormat(Class, NumberFormat)

addNumberFormat

public JSONConfig addNumberFormat(Number numericType,
                                  NumberFormat fmt)

Add a number format for a particular type that extends Number. You can set one format per type that extends Number. All JSON conversions that use this config will use the given format for output of numbers of the given class.

This could allow you to limit the number of digits printed for a float or a double for example, getting rid of excess digits caused by rounding problems in floating point numbers.

Parameters:

numericType - The object.

fmt - The number format.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.addNumberFormat(Number, NumberFormat)

addNumberFormats

public JSONConfig addNumberFormats(Map<Class<? extends Number>,NumberFormat> numFmtMap)

Add a map of number formats to the current map of number formats.

Parameters:

numFmtMap - The input map.

Returns:

this JSONConfig object.

Since:

1.4

See Also:

JSONConfigDefaults.addNumberFormats(Map)

removeNumberFormat

public JSONConfig removeNumberFormat(Class<? extends Number> numericClass)

Remove the requested class from the number formats that this config knows about.

Parameters:

numericClass - The class.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.removeNumberFormat(Class)

removeNumberFormat

public JSONConfig removeNumberFormat(Number num)

Remove the requested class from the number formats that this config knows about.

Parameters:

num - An object that implements Number.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.removeNumberFormat(Number)

clearNumberFormats

public JSONConfig clearNumberFormats()

Clear all number formats.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.clearNumberFormats()

setDateGenFormat

public JSONConfig setDateGenFormat(DateFormat fmt)

Set the date string generation format used when encodeDatesAsStrings or encodeDatesAsObjects are true. If you do not set the date formatter, it will use an ISO 8601 extended format formatter will be used when formatting dates. The format is yyyy-MM-dd'T'HH:mm:ss.sss'Z'

Parameters:

fmt - the dateFormat to set

Returns:

this JSONConfig object.

Since:

1.4

See Also:

JSONConfigDefaults.setDateGenFormat(DateFormat)

setDateGenFormat

public DateFormat setDateGenFormat(String fmtStr)

Set the date string generation format.

Parameters:

fmtStr - passed to the constructor SimpleDateFormat.SimpleDateFormat(String,Locale) using the locale from this config object.

Returns:

The format that was created.

Since:

1.4

See Also:

JSONConfigDefaults.setDateGenFormat(String)

clearDateGenFormat

public JSONConfig clearDateGenFormat()

Clear date generation format.

Returns:

this JSONConfig object.

Since:

1.4

See Also:

JSONConfigDefaults.clearDateGenFormat()

addDateParseFormat

public JSONConfig addDateParseFormat(DateFormat fmt)

Add a date parsing format to the list of parsing formats. When parsing date strings, they will be tried in the same order that they were added until one works.

Parameters:

fmt - A date parsing format.

Returns:

this JSONConfig object.

Since:

1.4

See Also:

JSONConfigDefaults.addDateParseFormat(DateFormat)

addDateParseFormat

public DateFormat addDateParseFormat(String fmtStr)

Add a date parsing format to the list of parsing formats. When parsing date strings, they will be tried in the same order that they were added until one works.

Parameters:

fmtStr - Passed to SimpleDateFormat.SimpleDateFormat(String,Locale) using the locale from this config object to create a DateFormat.

Returns:

The format that gets created.

Since:

1.4

See Also:

JSONConfigDefaults.addDateParseFormat(String)

addDateParseFormats

public JSONConfig addDateParseFormats(Collection<? extends DateFormat> fmts)

Add a collection of date parsing formats to the list of date parsing formats.

Parameters:

fmts - A collection of date parsing formats.

Returns:

this JSONConfig object.

Since:

1.4

See Also:

JSONConfigDefaults.addDateParseFormats(Collection)

clearDateParseFormats

public JSONConfig clearDateParseFormats()

Clear any date parse formats.

Returns:

this JSONConfig object.

Since:

1.4

See Also:

JSONConfigDefaults.clearDateParseFormats()

getIndentPadding

public IndentPadding getIndentPadding()

Get the padding object.

Returns:

the padding object.

Since:

1.7

See Also:

JSONConfigDefaults.getIndentPadding()

setIndentPadding

public JSONConfig setIndentPadding(IndentPadding indentPadding)

Set the padding object.

Parameters:

indentPadding - the padding object.

Returns:

this JSONConfig object.

Since:

1.7

See Also:

JSONConfigDefaults.setIndentPadding(IndentPadding)

getReflectionPrivacy

public int getReflectionPrivacy()

Get the reflection privacy level.

Returns:

the reflection privacy level.

Since:

1.9

See Also:

ReflectUtil.PRIVATE, ReflectUtil.PACKAGE, ReflectUtil.PROTECTED, ReflectUtil.PUBLIC, JSONConfigDefaults.getReflectionPrivacy()

setReflectionPrivacy

public JSONConfig setReflectionPrivacy(int reflectionPrivacy)

Set the privacy level for reflection. Default is ReflectUtil.PUBLIC.

Parameters:

reflectionPrivacy - the level to set

Returns:

this JSONConfig object.

Since:

1.9

See Also:

ReflectUtil.PRIVATE, ReflectUtil.PACKAGE, ReflectUtil.PROTECTED, ReflectUtil.PUBLIC, JSONConfigDefaults.setReflectionPrivacy(int)

isReflectClass

public boolean isReflectClass(Object obj)

Return true if the given class is in the set of classes being automatically reflected.

Parameters:

obj - An object to check

Returns:

true if objects of the given type are reflected.

Since:

1.9

See Also:

JSONConfigDefaults.isReflectClass(Object)

getReflectedClass

public JSONReflectedClass getReflectedClass(Object obj)

Get the JSONReflectedClass for the given object if it is stored. The main reason that you might want to use this is to modify the fields or aliases that are reflected in the class.

Parameters:

obj - the class being reflected.

Returns:

The JSONReflectedClass object or null if one is not stored.

See Also:

JSONConfigDefaults.getReflectedClass(Object)

addReflectClass

public JSONConfig addReflectClass(Object obj)

Add the class of the given object to the set of classes that automatically get reflected. If the object is an array, Iterable or Enumeration, then all objects in it will be added.

Parameters:

obj - The object whose class to add to the reflect list.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

JSONReflectedClass, addReflectClasses(Collection), addReflectClassByName(String), setReflectUnknownObjects(boolean), JSONConfigDefaults.addReflectClass(Object)

addReflectClassByName

public JSONConfig addReflectClassByName(String className)
                                 throws ClassNotFoundException

Add the given class to the set of classes to be reflected.

If you wish to use reflection with fields, you can append the field names to the class name, separated by commas before each field name. Field names which do not look like valid Java identifier names will be silently discarded. For example, if you want to reflect a class called "org.example.Widget" and it has fields called "a", "b" and "c" but you only want "a" and "c", then you can pass "org.example.Widget,a,c" to this method.

If you wish to use custom field names with reflection you can use name=alias pairs separated by commas as with the field names. For example, if you want to reflect a class called "org.example.Widget" and it has a field called "foo" but you want that field encoded as "bar" you can pass "org.example.Widget,foo=bar" to this method.

Parameters:

className - The name of the class suitable for ClassLoader.loadClass(String) followed optionally by a comma separated list of field names and/or field aliases.

Returns:

this JSONConfig object.

Throws:

ClassNotFoundException - If the class cannot be loaded.

Since:

1.9.2

See Also:

addReflectClass(Object), addReflectClasses(Collection), setReflectUnknownObjects(boolean), JSONConfigDefaults.addReflectClassByName(String)

addReflectClasses

public JSONConfig addReflectClasses(Collection<?> classes)

Add the classes of all of the given objests to the list of classes that automatically get reflected.

Parameters:

classes - The objects to reflect.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

JSONReflectedClass, addReflectClass(Object), addReflectClassByName(String), setReflectUnknownObjects(boolean), JSONConfigDefaults.addReflectClasses(Collection)

removeReflectClass

public JSONConfig removeReflectClass(Object obj)

Remove the given class from the list of automatically reflected classes. If the object is an array, Iterable or Enumeration, then all objects in it will be removed.

Parameters:

obj - An object of the type to be removed from the reflect list.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

JSONConfigDefaults.removeReflectClass(Object)

removeReflectClasses

public JSONConfig removeReflectClasses(Collection<?> classes)

Remove the given classes from the list of automatically reflected classes.

Parameters:

classes - A collection objects of the types to be removed from the reflect list.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

JSONConfigDefaults.removeReflectClasses(Collection)

clearReflectClasses

public JSONConfig clearReflectClasses()

Clear all reflection classes, disabling all automatic reflection.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

JSONConfigDefaults.clearReflectClasses()

getUnmatchedSurrogatePolicy

public int getUnmatchedSurrogatePolicy()

Get the policy for unmatched surrogates.

Returns:

the policy for unmatched surrogates.

See Also:

REPLACE, DISCARD, EXCEPTION, ESCAPE, PASS, JSONConfigDefaults.getUnmatchedSurrogatePolicy()

setUnmatchedSurrogatePolicy

public JSONConfig setUnmatchedSurrogatePolicy(int unmatchedSurrogatePolicy)

Tell JSONUtil what to do when it encounters unmatched surrogates in strings and identifiers. The permitted values are:

• REPLACE - Replace with the Unicode replacement character U+FFFD (default)
• DISCARD - Discard them.
• EXCEPTION - Throw an UnmatchedSurrogateException
• ESCAPE - Include them but escape them
• PASS - Pass them through unmodified.

Any other value will be ignored.

Parameters:

unmatchedSurrogatePolicy - the unmatchedSurrogatePolicy to set

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setUnmatchedSurrogatePolicy(int)

getUndefinedCodePointPolicy

public int getUndefinedCodePointPolicy()

Get the policy for undefined code points.

Returns:

the policy for undefined code points.

See Also:

REPLACE, DISCARD, EXCEPTION, ESCAPE, PASS, JSONConfigDefaults.getUndefinedCodePointPolicy()

setUndefinedCodePointPolicy

public JSONConfig setUndefinedCodePointPolicy(int undefinedCodePointPolicy)

Tell JSONUtil what to do when it encounters undefined code points in strings and identifiers. The permitted values are:

• REPLACE - Replace with the Unicode replacement character U+FFFD (default)
• DISCARD - Discard them.
• EXCEPTION - Throw an UndefinedCodePointException
• ESCAPE - Include them but escape them
• PASS - Pass them through unmodified.

Any other value will be ignored.

In code that interprets inline escapes, when an undefined code point is specified by an ECMAScript 6 code point escape and that value is greater than the maximum permissible code point (U+10FFFF), then for ESCAPE or PASS the code point will be set to the Unicode replacement character U+FFFD to indicate that the character has been replaced.

Parameters:

undefinedCodePointPolicy - the undefinedCodePointPolicy to set

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setUndefinedCodePointPolicy(int)

setBadCharacterPolicy

public JSONConfig setBadCharacterPolicy(int badCharacterPolicy)

Convenience method to call both setUnmatchedSurrogatePolicy(int) and setUndefinedCodePointPolicy(int) using the same value.

Parameters:

badCharacterPolicy - the badCharacterPolicy to set

Returns:

this JSONConfig object.

See Also:

REPLACE, DISCARD, EXCEPTION, ESCAPE, PASS, JSONConfigDefaults.setBadCharacterPolicy(int)

isValidatePropertyNames

public boolean isValidatePropertyNames()

Check if property names will be validated.

Returns:

true if property names are set to be validated.

See Also:

JSONConfigDefaults.isValidatePropertyNames()

setValidatePropertyNames

public JSONConfig setValidatePropertyNames(boolean validatePropertyNames)

If true, then property names will be validated. Default is true. Setting this to false will speed up generation of JSON but will not make sure that property names are valid. If execution speed of generating JSON is an issue for you, then you may want to do most of your development and testing with this set to true but switch to false when you release.

When validation is enabled and fullJSONIdentifierCodePoints is false, then only code points which are allowed in identifiers will be permitted as per the ECMAScript 5 or 6 standard as well as disallowing reserved words as per the JSON spec. If fullJSONIdentifierCodePoints is true, then all code points permitted by the ECMA JSON standard will be permitted, though many of those are not permitted by the ECMAScript standard and will break if evaluated by a Javascript eval().

It will also check for duplicate property names in the same object, which is possible because keys in maps are not required to be String objects and it's possible (though not likely) for two objects which are not equal to have the same result from a toString() method.

Parameters:

validatePropertyNames - Set to false to disable property name validation.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setValidatePropertyNames(boolean)

isDetectDataStructureLoops

public boolean isDetectDataStructureLoops()

Return true if data structure loops will be detected.

Returns:

true if data structure loops will be detected.

See Also:

JSONConfigDefaults.isDetectDataStructureLoops()

setDetectDataStructureLoops

public JSONConfig setDetectDataStructureLoops(boolean detectDataStructureLoops)

Enable or disable data structure loop detection. Default is true. Do not change this in the middle of a toJSON call, which you could theoretically do from a JSONAble object. It could break the detection system and if you have a loop, you could get recursion until the stack overflows, which would be bad.

Parameters:

detectDataStructureLoops - If true then JSONUtil will attempt to detect loops in data structures.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setDetectDataStructureLoops(boolean)

isEscapeBadIdentifierCodePoints

public boolean isEscapeBadIdentifierCodePoints()

Find out if bad identifier code points will be escaped.

Returns:

the the identifier escape policy.

See Also:

JSONConfigDefaults.isEscapeBadIdentifierCodePoints()

setEscapeBadIdentifierCodePoints

public JSONConfig setEscapeBadIdentifierCodePoints(boolean escapeBadIdentifierCodePoints)

If true, then any bad code points in identifiers will be escaped. Default is false.

Parameters:

escapeBadIdentifierCodePoints - the escapeBadIdentifierCodePoints to set

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setEscapeBadIdentifierCodePoints(boolean)

isFullJSONIdentifierCodePoints

public boolean isFullJSONIdentifierCodePoints()

Get the full JSON identifier code points policy.

Returns:

the fullJSONIdentifierCodePoints

See Also:

JSONConfigDefaults.isFullJSONIdentifierCodePoints()

setFullJSONIdentifierCodePoints

public JSONConfig setFullJSONIdentifierCodePoints(boolean fullJSONIdentifierCodePoints)

If true, then the full set of identifier code points permitted by the JSON standard will be allowed instead of the more restrictive set permitted by the ECMAScript standard. Use of characters not permitted by the ECMAScript standard will cause an error if parsed by Javascript eval().

Parameters:

fullJSONIdentifierCodePoints - If true, then allow all code points permitted by the JSON standard in identifiers.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setFullJSONIdentifierCodePoints(boolean)

isFastStrings

public boolean isFastStrings()

Get the fastStrings policy.

Returns:

the fastStrings policy

See Also:

JSONConfigDefaults.isFastStrings()

setFastStrings

public JSONConfig setFastStrings(boolean fastStrings)

If true, then string values will be copied to the output with no escaping or validation.

Only use this if you know that you have no unescaped characters in the range U+0000-U+001F or unescaped backslash or forward slash or double quote in your strings. If you want your JSON to be parsable by Javascript eval() then you also need to make sure that you don't have U+2028 (line separator) or U+2029 (paragraph separator).

That said, if you are encoding a lot of large strings, this can improve performance by eliminating the check for characters that need to be escaped.

Parameters:

fastStrings - If true, then string values will be copied as is with no escaping or validation.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setFastStrings(boolean)

isEncodeNumericStringsAsNumbers

public boolean isEncodeNumericStringsAsNumbers()

If true, then strings will be checked for number patterns and if they look like numbers, then they won't be quoted.

Returns:

the isEncodeNumericStringsAsNumbers

See Also:

JSONConfigDefaults.isEncodeNumericStringsAsNumbers()

setEncodeNumericStringsAsNumbers

public JSONConfig setEncodeNumericStringsAsNumbers(boolean encodeNumericStringsAsNumbers)

If true, then strings will be checked for number patterns and if they look like numbers, then they won't be quoted. In JSONParser, strings will examined and if they look like numbers, then they will be parsed as numbers in the output. Default is false.

Parameters:

encodeNumericStringsAsNumbers - the encodeNumericStringsAsNumbers to set

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setEncodeNumericStringsAsNumbers(boolean)

isEscapeNonAscii

public boolean isEscapeNonAscii()

Check if non-ascii characters are to be encoded as Unicode escapes.

Returns:

true if non-ascii characters should be encoded with Unicode escapes.

See Also:

JSONConfigDefaults.isEscapeNonAscii()

setEscapeNonAscii

public JSONConfig setEscapeNonAscii(boolean escapeNonAscii)

If you want non-ascii characters encoded as Unicode escapes in strings and identifiers, you can do that by setting this to true. Default is false. One reason that you might want to do this is when debugging code that is working with code points for which you do not have a usable font. If true, then escapeSurrogates will be forced to false (it would be redundant).

Parameters:

escapeNonAscii - set to true if you want non-ascii to be Unicode escaped.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setEscapeNonAscii(boolean)

isEscapeSurrogates

public boolean isEscapeSurrogates()

Return the escape surrogates policy.

Returns:

the escape surrogates policy.

See Also:

JSONConfigDefaults.isEscapeSurrogates()

setEscapeSurrogates

public JSONConfig setEscapeSurrogates(boolean escapeSurrogates)

If true then all surrogates will be escaped in strings and identifiers and escapeNonAscii will be forced to false.

Parameters:

escapeSurrogates - the escapeSurrogates to set

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setEscapeSurrogates(boolean)

isUnEscapeWherePossible

public boolean isUnEscapeWherePossible()

The unEscape policy.

Returns:

the unEscape policy.

See Also:

JSONConfigDefaults.isUnEscapeWherePossible()

setUnEscapeWherePossible

public JSONConfig setUnEscapeWherePossible(boolean unEscapeWherePossible)

If true then where possible, undo inline escapes in strings before going through normal string processing. Default is false. When false, escapes in strings are escaped unless isPassThroughEscapes() is set to true. If true, then all recognized inline escapes are unescaped before the string goes through normal processing. Note that this has no effect if isFastStrings() returns true. This option can be useful if you have strings with some of the Javascript escapes which are illegal in JSON.

Note that this does not apply to property names. It is only applied to string values.

Parameters:

unEscapeWherePossible - If true then where possible, undo inline escapes in strings.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setUnEscapeWherePossible(boolean)

isPassThroughEscapes

public boolean isPassThroughEscapes()

Get the pass through escapes policy.

Returns:

The pass through escapes policy.

See Also:

JSONConfigDefaults.isPassThroughEscapes()

setPassThroughEscapes

public JSONConfig setPassThroughEscapes(boolean passThroughEscapes)

If true, then legal escapes in strings will be passed through unchanged. If false, then the backslash that starts the escape will be escaped. The normal default is false.

Parameters:

passThroughEscapes - If true, then pass escapes through.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setPassThroughEscapes(boolean)

isEncodeDatesAsStrings

public boolean isEncodeDatesAsStrings()

Get the encode dates as strings policy.

Returns:

the encodeDatesAsStrings policy.

See Also:

JSONConfigDefaults.isEncodeDatesAsStrings()

setEncodeDatesAsStrings

public JSONConfig setEncodeDatesAsStrings(boolean encodeDatesAsStrings)

If true, then Date objects will be encoded as ISO 8601 date strings or a custom date format if you have called setDateGenFormat(DateFormat). If you set this to true, then encodeDatesAsObjects will be set to false.

Parameters:

encodeDatesAsStrings - the encodeDatesAsStrings to set

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setEncodeDatesAsStrings(boolean)

isReflectUnknownObjects

public boolean isReflectUnknownObjects()

Get the reflection of unknown objects policy.

Returns:

the reflectUnknownObjects policy.

See Also:

JSONConfigDefaults.isReflectUnknownObjects()

setReflectUnknownObjects

public JSONConfig setReflectUnknownObjects(boolean reflectUnknownObjects)

Set the unknown object reflection encoding policy. If true, then any time that an unknown object is encountered, this package will attempt to use reflection to encode it. Default is false. When false, then unknown objects will have their toString() method called unless their class has been added to the list of classes to be reflected.

Parameters:

reflectUnknownObjects - If true, then attempt to use reflection to encode objects which are otherwise unknown.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

addReflectClass(Object), addReflectClasses(Collection), addReflectClassByName(String), JSONConfigDefaults.setReflectUnknownObjects(boolean)

isPreciseNumbers

public boolean isPreciseNumbers()

Get the preciseNumbers policy.

Returns:

The preciseNumbers policy.

Since:

1.9

See Also:

JSONConfigDefaults.isPreciseNumbers()

setPreciseNumbers

public JSONConfig setPreciseNumbers(boolean preciseNumbers)

If true then integer numbers which are not exactly representable by a 64 bit double precision floating point number will be quoted in the output. If false, then they will be unquoted, and precision will likely be lost in the interpreter.

Parameters:

preciseNumbers - If true then quote integer numbers that lose precision in 64-bit floating point.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

JSONConfigDefaults.setPreciseNumbers(boolean)

isSmallNumbers

public boolean isSmallNumbers()

Get the smallNumbers policy.

Returns:

The smallNumbers policy.

Since:

1.9

See Also:

JSONConfigDefaults.isSmallNumbers()

setSmallNumbers

public JSONConfig setSmallNumbers(boolean smallNumbers)

If true then JSONParser will attempt to minimize the storage used for all numbers. Decimal numbers will be reduced to floats instead of doubles if it can done without losing precision. Integer numbers will be reduced from long to int or short or byte if they fit.

Parameters:

smallNumbers - If true then numbers will be made to use as little memory as possible.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

JSONConfigDefaults.setSmallNumbers(boolean)

isUsePrimitiveArrays

public boolean isUsePrimitiveArrays()

The primitive arrays policy.

Returns:

the usePrimitiveArrays policy.

Since:

1.9

See Also:

JSONConfigDefaults.isUsePrimitiveArrays()

setUsePrimitiveArrays

public JSONConfig setUsePrimitiveArrays(boolean usePrimitiveArrays)

If true, then when JSONParser encounters a JSON array of non-null wrappers of primitives and those primitives are all compatible with each other, then instead of an ArrayList of wrappers for those primitives it will create an array of those primitives in order to save memory.

This works for booleans and numbers. It will also convert an array of single character strings into an array of chars. Arrays of numbers will attempt to use the least complex type that does not lose information. You could easily end up with an array of bytes if all of your numbers are integers in the range -128 to 127. This option is meant to save as much memory as possible.

Parameters:

usePrimitiveArrays - if true, then the parser will create arrays of primitives as applicable.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

JSONConfigDefaults.setUsePrimitiveArrays(boolean)

isCacheReflectionData

public boolean isCacheReflectionData()

Get the the cacheReflectionData policy.

Returns:

the cacheReflectionData policy.

Since:

1.9

See Also:

JSONConfigDefaults.isCacheReflectionData()

setCacheReflectionData

public JSONConfig setCacheReflectionData(boolean cacheReflectionData)

If true, then when an object is reflected its reflection data will be cached to improve performance on subsequent reflections of objects of its class.

Parameters:

cacheReflectionData - if true, then cache reflection data.

Returns:

this JSONConfig object.

Since:

1.9

See Also:

JSONConfigDefaults.setCacheReflectionData(boolean)

isQuoteIdentifier

public boolean isQuoteIdentifier()

Find out what the identifier quote policy is.

Returns:

If true, then all identifiers will be quoted.

See Also:

JSONConfigDefaults.isQuoteIdentifier()

setQuoteIdentifier

public JSONConfig setQuoteIdentifier(boolean quoteIdentifier)

Control whether identifiers are quoted or not. By setting this to false, you save two characters per identifier, except for oddball identifiers that contain characters that must be quoted. Default is true, because that's what the ECMA JSON spec says to do. It might have issues in other things that read JSON and need 100% compliance with the spec. In particular, JQuery does NOT like it when you leave out the quotes. It wants the quotes according to the JSON spec. Javascript eval() tends to be just fine with having no quotes. Note that if you enable using keywords as identifiers and use a keyword as an identifier, that will force quotes anyway. If you use characters that require surrogate pairs, that will also force quotes.

Parameters:

quoteIdentifier - If true, then all identifiers will be quoted. If false, then only those that really need quotes will be quoted.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setQuoteIdentifier(boolean)

isUseECMA6

public boolean isUseECMA6()

Find out if ECMAScript 6 code point escapes are enabled.

Returns:

The ECMAScript 6 policy.

See Also:

JSONConfigDefaults.isUseECMA6()

setUseECMA6

public JSONConfig setUseECMA6(boolean useECMA6)

If you set this to true, then when JSONUtil generates Unicode escapes, it will use ECMAScript 6 code point escapes if they are shorter than code unit escapes. This is not standard JSON and not yet widely supported by Javascript interpreters. It also allows identifiers to have letter numbers in addition to other letters. Default is false.

Parameters:

useECMA6 - If true, use EMCAScript 6 code point escapes and allow ECMAScript 6 identifier character set.

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setUseECMA6(boolean)

isAllowReservedWordsInIdentifiers

public boolean isAllowReservedWordsInIdentifiers()

Get the allowReservedWordsInIdentifiers policy.

Returns:

the allowReservedWordsInIdentifiers policy.

See Also:

JSONConfigDefaults.isAllowReservedWordsInIdentifiers()

setAllowReservedWordsInIdentifiers

public JSONConfig setAllowReservedWordsInIdentifiers(boolean allowReservedWordsInIdentifiers)

If true then reserved words will be allowed in identifiers even when identifier validation is enabled. Default is false.

Parameters:

allowReservedWordsInIdentifiers - the allowReservedWordsInIdentifiers to set

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setAllowReservedWordsInIdentifiers(boolean)

isEncodeDatesAsObjects

public boolean isEncodeDatesAsObjects()

Get the encode dates policy.

Returns:

the encodeDates policy.

See Also:

JSONConfigDefaults.isEncodeDatesAsObjects()

setEncodeDatesAsObjects

public JSONConfig setEncodeDatesAsObjects(boolean encodeDatesAsObjects)

If true, then Date objects will be encoded as Javascript dates, using new Date(dateString). If you set this to true, then encodeDatesAsStrings will be set to false.

Parameters:

encodeDatesAsObjects - the encodeDates to set

Returns:

this JSONConfig object.

See Also:

JSONConfigDefaults.setEncodeDatesAsObjects(boolean)

isFormatDates

public boolean isFormatDates()

Find out if special date formatting is enabled.

Returns:

true if encodeDatesAsObjects or encodeDatesAsStrings is true.