com.unboundid.util.json
Class JSONString

java.lang.Object
  com.unboundid.util.json.JSONValue
      com.unboundid.util.json.JSONString

All Implemented Interfaces:

java.io.Serializable

@NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class JSONString
extends JSONValue

This class provides an implementation of a JSON value that represents a string of Unicode characters. The string representation of a JSON string must start and end with the double quotation mark character, and a Unicode (preferably UTF-8) representation of the string between the quotes. The following special characters must be escaped:

• The double quotation mark (Unicode character U+0022) must be escaped as either \" or \u0022.
• The backslash (Unicode character U+005C) must be escaped as either \\ or \u005C.
• All ASCII control characters (Unicode characters U+0000 through U+001F) must be escaped. They can all be escaped by prefixing the four-hexadecimal-digit Unicode character code with \u, like \u0000 to represent the ASCII null character U+0000. For certain characters, a more user-friendly escape sequence is also defined:
  • The horizontal tab character can be escaped as either \t or \u0009.
  • The newline character can be escaped as either \n or \u000A.
  • The formfeed character can be escaped as either \f or \u000C.
  • The carriage return character can be escaped as either \r or \u000D.

In addition, any other character may optionally be escaped by placing the \u prefix in front of each four-hexadecimal digit sequence in the UTF-16 representation of that character. For example, the "LATIN SMALL LETTER N WITH TILDE" character U+00F1 may be escaped as \u00F1, while the "MUSICAL SYMBOL G CLEF" character U+1D11E may be escaped as \uD834\uDD1E. And while the forward slash character is not required to be escaped in JSON strings, it can be escaped using \/ as a more human-readable alternative to \u002F.

The string provided to the JSONString(String) constructor should not have any escaping performed, and the string returned by the stringValue() method will not have any escaping performed. These methods work with the Java string that is represented by the JSON string.

If this JSON string was parsed from the string representation of a JSON object, then the value returned by the toString() method (or appended to the buffer provided to the toString(StringBuilder) method) will be the string representation used in the JSON object that was parsed. Otherwise, this class will generate an appropriate string representation, which will be surrounded by quotation marks and will have the minimal required encoding applied.

The string returned by the toNormalizedString() method (or appended to the buffer provided to the toNormalizedString(StringBuilder) method) will be generated by converting it to lowercase, surrounding it with quotation marks, and using the \u-style escaping for all characters other than the following (as contained in the LDAP printable character set defined in RFC 4517 section 3.2, and indicated by the StaticUtils.isPrintable(char) method):

• All uppercase ASCII alphabetic letters (U+0041 through U+005A).
• All lowercase ASCII alphabetic letters (U+0061 through U+007A).
• All ASCII numeric digits (U+0030 through U+0039).
• The ASCII space character U+0020.
• The ASCII single quote (aka apostrophe) character U+0027.
• The ASCII left parenthesis character U+0028.
• The ASCII right parenthesis character U+0029.
• The ASCII plus sign character U+002B.
• The ASCII comma character U+002C.
• The ASCII minus sign (aka hyphen) character U+002D.
• The ASCII period character U+002E.
• The ASCII forward slash character U+002F.
• The ASCII colon character U+003A.
• The ASCII equals sign character U+003D.
• The ASCII question mark character U+003F.

See Also:

Serialized Form

Constructor Summary

JSONString(java.lang.String value)
Creates a new JSON string.

Method Summary

void	appendToJSONBuffer(JSONBuffer buffer) Appends this value to the provided JSON buffer.
void	appendToJSONBuffer(java.lang.String fieldName, JSONBuffer buffer) Appends a field with the given name and this value to the provided JSON buffer.
boolean	equals(JSONString s, boolean ignoreCase) Indicates whether the value of this JSON string matches that of the provided string, optionally ignoring differences in capitalization.
boolean	equals(JSONValue v, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder) Indicates whether this JSON value is considered equal to the provided JSON value, subject to the specified constraints.
boolean	equals(java.lang.Object o) Indicates whether the provided object is equal to this JSON value.
int	hashCode() Retrieves a hash code for this JSON value.
java.lang.String	stringValue() Retrieves the string value for this object.
java.lang.String	toNormalizedString() Retrieves a normalized string representation of this value.
void	toNormalizedString(java.lang.StringBuilder buffer) Appends a normalized string representation of this value to the provided buffer.
java.lang.String	toSingleLineString() Retrieves a single-line string representation of this value as it should appear in a JSON object, including any necessary quoting, escaping, etc.
void	toSingleLineString(java.lang.StringBuilder buffer) Appends a single-line string representation of this value (as it should appear in a JSON object, including any necessary quoting, escaping, etc.) to the provided buffer.
java.lang.String	toString() Retrieves a string representation of this value as it should appear in a JSON object, including any necessary quoting, escaping, etc.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this value (as it should appear in a JSON object, including any necessary quoting, escaping, etc.) to the provided buffer.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JSONString

public JSONString(java.lang.String value)

Creates a new JSON string.

Parameters:

value - The string to represent in this JSON value. It must not be null.

Method Detail

stringValue

public java.lang.String stringValue()

Retrieves the string value for this object. This will be the interpreted value, without the surrounding quotation marks or escaping.

Returns:

The string value for this object.

hashCode

public int hashCode()

Retrieves a hash code for this JSON value.

Specified by:

hashCode in class JSONValue

Returns:

The hash code for this JSON value.

equals

public boolean equals(java.lang.Object o)

Indicates whether the provided object is equal to this JSON value.

Specified by:

equals in class JSONValue

Parameters:

o - The object to compare against this JSON value.

Returns:

true if the provided object is considered equal to this JSON value, or false if not.

equals

public boolean equals(JSONString s,
                      boolean ignoreCase)

Indicates whether the value of this JSON string matches that of the provided string, optionally ignoring differences in capitalization.

Parameters:

s - The JSON string to compare against this JSON string. It must not be null.

ignoreCase - Indicates whether to ignore differences in capitalization.

Returns:

true if the value of this JSON string matches the value of the provided string (optionally ignoring differences in capitalization), or false if not.

equals

public boolean equals(JSONValue v,
                      boolean ignoreFieldNameCase,
                      boolean ignoreValueCase,
                      boolean ignoreArrayOrder)

Indicates whether this JSON value is considered equal to the provided JSON value, subject to the specified constraints. Note that not all constraints will apply to all data types.

Specified by:

equals in class JSONValue

Parameters:

v - The JSON value for which to make the determination. It must not be null.

ignoreFieldNameCase - Indicates whether to ignore differences in the capitalization of JSON field names.

ignoreValueCase - Indicates whether to ignore differences in the capitalization of JSON values that represent strings.

ignoreArrayOrder - Indicates whether to ignore differences in the order of elements in JSON arrays.

Returns:

true if this JSON value is considered equal to the provided JSON value (subject to the specified constraints), or false if not.

toString

public java.lang.String toString()

Retrieves a string representation of this value as it should appear in a JSON object, including any necessary quoting, escaping, etc.

Specified by:

toString in class JSONValue

Returns:

A string representation of this value as it should appear in a JSON object.

toString

public void toString(java.lang.StringBuilder buffer)

Appends a string representation of this value (as it should appear in a JSON object, including any necessary quoting, escaping, etc.) to the provided buffer.

Specified by:

toString in class JSONValue

Parameters:

buffer - The buffer to which the information should be appended.

toSingleLineString

public java.lang.String toSingleLineString()

Retrieves a single-line string representation of this value as it should appear in a JSON object, including any necessary quoting, escaping, etc.

Specified by:

toSingleLineString in class JSONValue

Returns:

A string representation of this value as it should appear in a JSON object.

toSingleLineString

public void toSingleLineString(java.lang.StringBuilder buffer)

Appends a single-line string representation of this value (as it should appear in a JSON object, including any necessary quoting, escaping, etc.) to the provided buffer.

Specified by:

toSingleLineString in class JSONValue

Parameters:

buffer - The buffer to which the information should be appended.

toNormalizedString

public java.lang.String toNormalizedString()

Retrieves a normalized string representation of this value. All equivalent JSON values must have equivalent normalized representations, even if there are other legal representations for the value.

Specified by:

toNormalizedString in class JSONValue

Returns:

A normalized string representation of this value.

toNormalizedString

public void toNormalizedString(java.lang.StringBuilder buffer)

Appends a normalized string representation of this value to the provided buffer. All equivalent JSON values must have equivalent normalized representations, even if there are other legal representations for the value.

Specified by:

toNormalizedString in class JSONValue

Parameters:

buffer - The buffer to which the information should be appended.

appendToJSONBuffer

public void appendToJSONBuffer(JSONBuffer buffer)

Appends this value to the provided JSON buffer. This will not include a field name, so it should only be used for Boolean value elements in an array.

Specified by:

appendToJSONBuffer in class JSONValue

Parameters:

buffer - The JSON buffer to which this value should be appended.

appendToJSONBuffer

public void appendToJSONBuffer(java.lang.String fieldName,
                               JSONBuffer buffer)

Appends a field with the given name and this value to the provided JSON buffer.

Specified by:

appendToJSONBuffer in class JSONValue

Parameters:

fieldName - The name to use for the field.

buffer - The JSON buffer to which this value should be appended.