Package com.github.tnakamot.json

Class JSONText

java.lang.Object

com.github.tnakamot.json.JSONText

public class JSONText
extends Object

Represents one JSON text.

Instances of this class is not immutable, but thread-safe.

Method Summary

Modifier and Type	Method	Description
@NotNull JSONValue	evaluate(@NotNull JSONPointer pointer)	Evaluate the given JSON Pointer and return the found JSON value.
@NotNull JSONValue	evaluate(@NotNull String pointer)	Evaluate the given JSON Pointer and return the found JSON value.
@NotNull JSONValue	evaluate(@NotNull String pointer, boolean fragment)	Evaluate the given JSON Pointer and return the found JSON value.
static @NotNull JSONText	fromFile(@NotNull File file)	Reads JSON text from a file and returns an instance of JSONText for further processing.
static @NotNull JSONText	fromString(@NotNull String str)	Convert the given String to an instance of JSONText.
static @NotNull JSONText	fromString(@NotNull String str, @Nullable String name)	Convert the given String to an instance of JSONText.
static @NotNull JSONText	fromURL(@NotNull URL url)	Reads JSON text from a URL and returns an instance of JSONText for further processing.
@NotNull String	get()	Returns the content of this JSON text as a string.
boolean	isParsed()	Returns whether this JSON text has been successfully parsed in the past.
@NotNull String	name()	Return a short name of the source of this JSON text.
@NotNull JSONParserResult	parse()	Parse this JSON text.
@NotNull JSONParserResult	parse(@NotNull JSONParserErrorHandlingOptions options)	Parse this JSON text.
@NotNull Object	source()	Return the object which represents the source of this JSON text.
@NotNull List<JSONToken>	tokens()	Tokenize this JSON text.
@NotNull List<JSONToken>	tokens(@NotNull JSONParserErrorHandlingOptions options)	Tokenize this JSON text.
String	toString()
@NotNull URI	uri()	Return a URI of the source of this JSON text.

Methods inherited from class java.lang.Object

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

Method Detail

get

@NotNull
public @NotNull String get()

Returns the content of this JSON text as a string.

Returns:

Contents of this JSON text.

source

@NotNull
public @NotNull Object source()

Return the object which represents the source of this JSON text.

Returns:

An instance of File, URL or String.

name

@NotNull
public @NotNull String name()

Return a short name of the source of this JSON text. This is useful to construct an error message of JSON parsers.

Returns:

name of this JSON text.

uri

@NotNull
public @NotNull URI uri()

Return a URI of the source of this JSON text.

tokens

@NotNull
public @NotNull List<JSONToken> tokens(@NotNull
                                       @NotNull JSONParserErrorHandlingOptions options)
                                throws IOException,
                                       JSONParserException

Tokenize this JSON text.

Parameters:

options - parser options

Returns:

Sequence of JSON tokens.

Throws:

IOException - if an I/O error occurs

JSONParserException - if there is a syntax error in JSON text

tokens

@NotNull
public @NotNull List<JSONToken> tokens()
                                throws IOException,
                                       JSONParserException

Tokenize this JSON text.

Returns:

Sequence of JSON tokens.

Throws:

IOException - if an I/O error occurs

JSONParserException - if there is a syntax error in JSON text

parse

@NotNull
public @NotNull JSONParserResult parse(@NotNull
                                       @NotNull JSONParserErrorHandlingOptions options)
                                throws IOException,
                                       JSONParserException

Parse this JSON text.

The returned instance is immutable.

Parameters:

options - parser options

Returns:

parse result

Throws:

JSONParserException - if there is a syntax error in the JSON text

IOException - if an I/O error occurs

See Also:

RFC 8259 - 2. JSON Grammer

parse

@NotNull
public @NotNull JSONParserResult parse()
                                throws IOException,
                                       JSONParserException

Parse this JSON text.

The returned instance is immutable.

Returns:

parse result

Throws:

JSONParserException - if there is a syntax error in the JSON text

IOException - if an I/O error occurs

See Also:

RFC 8259 - 2. JSON Grammer

isParsed

public boolean isParsed()

Returns whether this JSON text has been successfully parsed in the past.

If this method returns false, evaluate(String) and its variants result in IllegalStateException;

Returns:

whether this JSON text has been successfully parsed in the past.

evaluate

@NotNull
public @NotNull JSONValue evaluate(@NotNull
                                   @NotNull String pointer)
                            throws InvalidJSONPointerException

Evaluate the given JSON Pointer and return the found JSON value.

parse() (or its variant) must be successfully called before this method.

Note that this method results in InvalidJSONPointerException if this JSON text does not have any JSON value.

Parameters:

pointer - a string representation of a JSON Pointer

Returns:

the JSON value of the pointer evaluation result

Throws:

InvalidJSONPointerException - when the JSON Pointer has an error

IllegalStateException - if this JSON text has not been parsed yet

evaluate

@NotNull
public @NotNull JSONValue evaluate(@NotNull
                                   @NotNull String pointer,
                                   boolean fragment)
                            throws InvalidJSONPointerException

Evaluate the given JSON Pointer and return the found JSON value.

parse() (or its variant) must be successfully called before this method.

Note that this method results in InvalidJSONPointerException if this JSON text does not have any JSON value.

Parameters:

pointer - a string representation of a JSON Pointer

fragment - specify true to handle the given string as a URI fragment identifier starting with '#".

Returns:

the JSON value of the pointer evaluation result

Throws:

InvalidJSONPointerException - when the JSON Pointer has an error

IllegalStateException - if this JSON text has not been parsed yet

evaluate

@NotNull
public @NotNull JSONValue evaluate(@NotNull
                                   @NotNull JSONPointer pointer)
                            throws InvalidJSONPointerException

Evaluate the given JSON Pointer and return the found JSON value.

parse() (or its variant) must be successfully called before this method.

Note that this method results in InvalidJSONPointerException if this JSON text does not have any JSON value.

Parameters:

pointer - JSON pointer

Returns:

the JSON value of the pointer evaluation result

Throws:

InvalidJSONPointerException - when the JSON Pointer has an error

IllegalStateException - if this JSON text has not been parsed yet

toString

public String toString()

Overrides:

toString in class Object

fromFile

@NotNull
public static @NotNull JSONText fromFile(@NotNull
                                         @NotNull File file)
                                  throws IOException

Reads JSON text from a file and returns an instance of JSONText for further processing. The file must be encoded using UTF-8.

Parameters:

file - JSON text file.

Returns:

An instance of JSON text.

Throws:

IOException - in case of an I/O error

See Also:

RFC 8259 - 8.1. Character Encoding

fromURL

@NotNull
public static @NotNull JSONText fromURL(@NotNull
                                        @NotNull URL url)
                                 throws IOException,
                                        URISyntaxException

Reads JSON text from a URL and returns an instance of JSONText for further processing. The text must be encoded using UTF-8.

Parameters:

url - URL of a JSON text file.

Returns:

An instance of JSON text.

Throws:

IOException - if an I/O exception occurs

URISyntaxException - if this URL is not formatted strictly according to to RFC2396 and cannot be converted to a URI.

See Also:

RFC 8259 - 8.1. Character Encoding

fromString

@NotNull
public static @NotNull JSONText fromString(@NotNull
                                           @NotNull String str)

Convert the given String to an instance of JSONText.

The name of this source is automatically determined. See fromString(String, String) for more details.

Parameters:

str - A string which contains JSON text.

Returns:

An instance of JSON text.

See Also:

RFC 8259 - 8.1. Character Encoding, fromString(String, String)

fromString

@NotNull
public static @NotNull JSONText fromString(@NotNull
                                           @NotNull String str,
                                           @Nullable
                                           @Nullable String name)

Convert the given String to an instance of JSONText.

Specify the name, then name() returns the specified string. The specified name will be used, for example, for the parser to show an error message . With a meaningful name, the users of your application will be able to know which JSON text has a syntax error.

If the name is not specified (= null is given), the name is automatically determined by this library, but the users may not understand where does that the JSON text come from, so it is not recommended.

Parameters:

str - A string which contains JSON text.

name - A name of this source string.

Returns:

An instance of JSON text.

See Also:

RFC 8259 - 8.1. Character Encoding