Package 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
.
-
The horizontal tab character can be escaped as either
\
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 theJSONString(String)
constructor should not have any escaping performed, and the string returned by thestringValue()
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 thetoString()
method (or appended to the buffer provided to thetoString(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 thetoNormalizedString()
method (or appended to the buffer provided to thetoNormalizedString(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 theStaticUtils.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
Constructors Constructor Description JSONString(java.lang.String value)
Creates a new JSON string.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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 representation of this JSON string as it should appear in a JSON object, including the surrounding quotes and any appropriate escaping.java.lang.String
toNormalizedString(boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
Retrieves a normalized representation of this JSON string as it should appear in a JSON object, including the surrounding quotes and any appropriate escaping.void
toNormalizedString(java.lang.StringBuilder buffer)
Appends a normalized representation of this JSON string as it should appear in a JSON object, including the surrounding quotes and any appropriate escaping, to the provided buffer.void
toNormalizedString(java.lang.StringBuilder buffer, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
Appends a normalized representation of this JSON string as it should appear in a JSON object, including the surrounding quotes and any appropriate escaping, to the provided buffer.java.lang.String
toSingleLineString()
Retrieves a single-line representation of this JSON string as it should appear in a JSON object, including the surrounding quotation marks and any appropriate escaping.void
toSingleLineString(java.lang.StringBuilder buffer)
Appends a single-line string representation of this JSON string as it should appear in a JSON object, including the surrounding quotation marks and any appropriate escaping, to the provided buffer.java.lang.String
toString()
Retrieves a string representation of this JSON string as it should appear in a JSON object, including the surrounding quotation marks and any appropriate escaping To obtain the string to which this value refers without the surrounding quotation marks or escaping, use thestringValue()
method.void
toString(java.lang.StringBuilder buffer)
Appends a string representation of this JSON string as it should appear in a JSON object, including the surrounding quotation marks and any appropriate escaping, to the provided buffer.
-
-
-
Constructor Detail
-
JSONString
public JSONString(@NotNull java.lang.String value)
Creates a new JSON string.- Parameters:
value
- The string to represent in this JSON value. It must not benull
.
-
-
Method Detail
-
stringValue
@NotNull 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.
-
equals
public boolean equals(@Nullable java.lang.Object o)
Indicates whether the provided object is equal to this JSON value.
-
equals
public boolean equals(@NotNull 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 benull
.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), orfalse
if not.
-
equals
public boolean equals(@NotNull 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 classJSONValue
- Parameters:
v
- The JSON value for which to make the determination. It must not benull
.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), orfalse
if not.
-
toString
@NotNull public java.lang.String toString()
Retrieves a string representation of this JSON string as it should appear in a JSON object, including the surrounding quotation marks and any appropriate escaping To obtain the string to which this value refers without the surrounding quotation marks or escaping, use thestringValue()
method.
If the object containing this string was decoded from a string, then this method will use the same string representation as in that original object. Otherwise, the string representation will be constructed.
-
toString
public void toString(@NotNull java.lang.StringBuilder buffer)
Appends a string representation of this JSON string as it should appear in a JSON object, including the surrounding quotation marks and any appropriate escaping, to the provided buffer. To obtain the string to which this value refers without the surrounding quotation marks or escaping, use thestringValue()
method.
If the object containing this string was decoded from a string, then this method will use the same string representation as in that original object. Otherwise, the string representation will be constructed.
-
toSingleLineString
@NotNull public java.lang.String toSingleLineString()
Retrieves a single-line representation of this JSON string as it should appear in a JSON object, including the surrounding quotation marks and any appropriate escaping. To obtain the string to which this value refers without the surrounding quotation marks or escaping, use thestringValue()
method.- Specified by:
toSingleLineString
in classJSONValue
- Returns:
- A single-line representation of this value as it should appear in a JSON object.
-
toSingleLineString
public void toSingleLineString(@NotNull java.lang.StringBuilder buffer)
Appends a single-line string representation of this JSON string as it should appear in a JSON object, including the surrounding quotation marks and any appropriate escaping, to the provided buffer. To obtain the string to which this value refers without the surrounding quotation marks or escaping, use thestringValue()
method.- Specified by:
toSingleLineString
in classJSONValue
- Parameters:
buffer
- The buffer to which the information should be appended.
-
toNormalizedString
@NotNull public java.lang.String toNormalizedString()
Retrieves a normalized representation of this JSON string as it should appear in a JSON object, including the surrounding quotes and any appropriate escaping. The normalized representation will use the unescaped ASCII representation of all of the following characters:- The letters a through z (ASCII character codes 0x61 through 0x7A).
- The digits 0 through 9 (ASCII character codes 0x30 through 0x39).
- The space (ASCII character code 0x20).
- The single quote (ASCII character code 0x27).
- The left parenthesis (ASCII character code 0x28).
- The right parenthesis (ASCII character code 0x29).
- The plus sign (ASCII character code 0x2B).
- The comma (ASCII character code 0x2C).
- The hyphen (ASCII character code 0x2D).
- The period (ASCII character code 0x2E).
- The forward slash (ASCII character code 0x2F).
- The colon (ASCII character code 0x3A).
- The equal sign (ASCII character code 0x3D).
- The question mark (ASCII character code 0x3F).
- Specified by:
toNormalizedString
in classJSONValue
- Returns:
- A normalized representation of this JSON string as it should appear in a JSON object, including
-
toNormalizedString
public void toNormalizedString(@NotNull java.lang.StringBuilder buffer)
Appends a normalized representation of this JSON string as it should appear in a JSON object, including the surrounding quotes and any appropriate escaping, to the provided buffer. The normalized representation will use the unescaped ASCII representation of all of the following characters:- The letters a through z (ASCII character codes 0x61 through 0x7A).
- The digits 0 through 9 (ASCII character codes 0x30 through 0x39).
- The space (ASCII character code 0x20).
- The single quote (ASCII character code 0x27).
- The left parenthesis (ASCII character code 0x28).
- The right parenthesis (ASCII character code 0x29).
- The plus sign (ASCII character code 0x2B).
- The comma (ASCII character code 0x2C).
- The hyphen (ASCII character code 0x2D).
- The period (ASCII character code 0x2E).
- The forward slash (ASCII character code 0x2F).
- The colon (ASCII character code 0x3A).
- The equal sign (ASCII character code 0x3D).
- The question mark (ASCII character code 0x3F).
- Specified by:
toNormalizedString
in classJSONValue
- Parameters:
buffer
- The buffer to which the information should be appended.
-
toNormalizedString
@NotNull public java.lang.String toNormalizedString(boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
Retrieves a normalized representation of this JSON string as it should appear in a JSON object, including the surrounding quotes and any appropriate escaping. The normalized representation will use the unescaped ASCII representation of all of the following characters:- The letters a through z (ASCII character codes 0x61 through 0x7A).
- The letters A through Z (ASCII character codes 0x41 through 0x5A).
These characters will only be used if
ignoreValueCase
isfalse
. - The digits 0 through 9 (ASCII character codes 0x30 through 0x39).
- The space (ASCII character code 0x20).
- The single quote (ASCII character code 0x27).
- The left parenthesis (ASCII character code 0x28).
- The right parenthesis (ASCII character code 0x29).
- The plus sign (ASCII character code 0x2B).
- The comma (ASCII character code 0x2C).
- The hyphen (ASCII character code 0x2D).
- The period (ASCII character code 0x2E).
- The forward slash (ASCII character code 0x2F).
- The colon (ASCII character code 0x3A).
- The equal sign (ASCII character code 0x3D).
- The question mark (ASCII character code 0x3F).
- Specified by:
toNormalizedString
in classJSONValue
- Parameters:
ignoreFieldNameCase
- Indicates whether field names should be treated in a case-sensitive (iffalse
) or case-insensitive (iftrue
) manner.ignoreValueCase
- Indicates whether string field values should be treated in a case-sensitive (iffalse
) or case-insensitive (iftrue
) manner.ignoreArrayOrder
- Indicates whether the order of elements in an array should be considered significant (iffalse
) or insignificant (iftrue
).- Returns:
- A normalized representation of this JSON string as it should appear in a JSON object, including
-
toNormalizedString
public void toNormalizedString(@NotNull java.lang.StringBuilder buffer, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
Appends a normalized representation of this JSON string as it should appear in a JSON object, including the surrounding quotes and any appropriate escaping, to the provided buffer. The normalized representation will use the unescaped ASCII representation of all of the following characters:- The letters a through z (ASCII character codes 0x61 through 0x7A).
- The letters A through Z (ASCII character codes 0x41 through 0x5A).
These characters will only be used if
ignoreValueCase
isfalse
. - The digits 0 through 9 (ASCII character codes 0x30 through 0x39).
- The space (ASCII character code 0x20).
- The single quote (ASCII character code 0x27).
- The left parenthesis (ASCII character code 0x28).
- The right parenthesis (ASCII character code 0x29).
- The plus sign (ASCII character code 0x2B).
- The comma (ASCII character code 0x2C).
- The hyphen (ASCII character code 0x2D).
- The period (ASCII character code 0x2E).
- The forward slash (ASCII character code 0x2F).
- The colon (ASCII character code 0x3A).
- The equal sign (ASCII character code 0x3D).
- The question mark (ASCII character code 0x3F).
- Specified by:
toNormalizedString
in classJSONValue
- Parameters:
buffer
- The buffer to which the information should be appended.ignoreFieldNameCase
- Indicates whether field names should be treated in a case-sensitive (iffalse
) or case-insensitive (iftrue
) manner.ignoreValueCase
- Indicates whether string field values should be treated in a case-sensitive (iffalse
) or case-insensitive (iftrue
) manner.ignoreArrayOrder
- Indicates whether the order of elements in an array should be considered significant (iffalse
) or insignificant (iftrue
).
-
appendToJSONBuffer
public void appendToJSONBuffer(@NotNull 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 classJSONValue
- Parameters:
buffer
- The JSON buffer to which this value should be appended.
-
appendToJSONBuffer
public void appendToJSONBuffer(@NotNull java.lang.String fieldName, @NotNull JSONBuffer buffer)
Appends a field with the given name and this value to the provided JSON buffer.- Specified by:
appendToJSONBuffer
in classJSONValue
- Parameters:
fieldName
- The name to use for the field.buffer
- The JSON buffer to which this value should be appended.
-
-