net.openhft.saxophone.json

Class JsonParser

java.lang.Object

net.openhft.saxophone.json.JsonParser

public final class JsonParser
extends Object

A pull JSON parser, accepts chunks of JSON as Bytes.

Construction:

Parser.builder().applyAdapter(eventHandler).options(...).build();
 

Try to reuse the parser, because it's allocation cost is pretty high. It's safe and valid to use the parser just like newly created one after a reset() call. To reset handlers' state on parser reset, implement and provide ResetHook. Example usage:

class Foo {
     JsonParser parser = ...;

     // return true if parsing succeed
     boolean parse(Iterator<Bytes> chunks) {
         try {
             while (chunks.hasNext()) {
                 if (!parser.parse(chunks.next())) {
                     parser.reset();
                     return false;
                 }
             }
             return parser.finish();
         } finally {
             parser.reset();
         }
     }
 }
 

If you want to recover ParseException:

...
 boolean parse(Iterator<Bytes> chunks) throws IOException {
     try {
         try {
             while (chunks.hasNext()) {
                 if (!parser.parse(chunks.next())) {
                     parser.reset();
                     return false;
                 }
             }
             return parser.finish();
         } catch (ParseException e) {
             Throwable cause = e.getCause();
             if (cause instanceof IOException) {
                 throw (IOException) cause;
             } else {
                 System.err.println("Json is malformed!");
                 return false;
             }
         }
     } finally {
         parser.reset();
     }
 }
 

See Also:

builder()

Method Summary

Methods

Modifier and Type	Method and Description
static JsonParserBuilder	builder() Return a new parser builder.
boolean	finish() Processes the last token.
boolean	parse(net.openhft.lang.io.Bytes jsonText) Parses a portion of JSON from the given Bytes from it's position to limit.
void	reset() Resets the parser to clear "just like after construction" state.

Methods inherited from class java.lang.Object

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

Method Detail

builder

public static JsonParserBuilder builder()

Return a new parser builder.

There are no public constructors of JsonParser at the moment, and likely won't be, so configuring a builder and then call JsonParserBuilder.build() is the only way to construct the parser.

Returns:

a new parser builder

reset

public void reset()

Resets the parser to clear "just like after construction" state.

At the end ResetHook, if provided, is notified.

Reusing parsers is encouraged because parser allocation / garbage collection is pretty costly.

finish

public boolean finish()

Processes the last token.

If the JSON data portions given to parse(net.openhft.lang.io.Bytes) method by now since the previous reset() call, or call of this method, or parser construction don't comprise one or several complete JSON entities, and JsonParserOption.ALLOW_PARTIAL_VALUES is not set, ParseException is thrown.

Returns:

true if parsing successfully finished, false, if the handler of the last token cancelled parsing

Throws:

ParseException - if the given JSON is malformed (exact meaning of "malformed" depends on parser's options), or if the handler of the last token, if it was actually processed during this call, have thrown a checked exception, or if IntegerHandler is provided, the last token is an integer and it is out of primitive long range: greater than Long.MAX_VALUE or lesser than Long.MIN_VALUE

IllegalStateException - if parsing was cancelled or any exception was thrown in parse(net.openhft.lang.io.Bytes) call after the previous reset() call or parser construction

parse

public boolean parse(net.openhft.lang.io.Bytes jsonText)

Parses a portion of JSON from the given Bytes from it's position to limit. Position is incremented until there are no remaining bytes or a single top-level JSON object is parsed and JsonParserTopLevelStrategy.ALLOW_TRAILING_GARBAGE is set.

As this is a pull parser, the given JSON text may break at any character. If the JsonParserOption.ALLOW_PARTIAL_VALUES is not set, ParseException will be thrown only on finish() call.

As JSON tokens are parsed, appropriate event handlers are notified. To ensure that the last token is processed, call finish() afterwards.

Returns true if the parsing succeed and token handlers haven't send a cancel request (i. e. returned true all the way). If any handler returns false, parsing is terminated immediately and false is returned.

If one of the handlers throws a checked exception, it is wrapped with ParseException (and available through Throwable.getCause() later). If one of the handlers throws an unchecked exception (RuntimeException), it is rethrown without any processing.

Parameters:

jsonText - a portion of JSON to parse

Returns:

true if the parsing wasn't cancelled by handlers

Throws:

ParseException - if the given JSON is malformed (exact meaning of "malformed" depends on parser's options), or if one of the handlers throws a checked exception, or IntegerHandler is provided but parsed integer value is out of primitive long range: greater than Long.MAX_VALUE or lesser than Long.MIN_VALUE

IllegalStateException - if parsing was cancelled or any exception was thrown in this method after the previous reset() call or parser construction, or if the input JSON contains a token without corresponding handler assigned, and JsonParserBuilder.eachTokenMustBeHandled() is set to true.