com.arangodb.shaded.vertx.core.parsetools.JsonParser Maven / Gradle / Ivy
/*
* Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
* which is available at https://www.apache.org/licenses/LICENSE-2.0.
*
* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
*/
package com.arangodb.shaded.vertx.core.parsetools;
import com.arangodb.shaded.vertx.codegen.annotations.Fluent;
import com.arangodb.shaded.vertx.codegen.annotations.VertxGen;
import com.arangodb.shaded.vertx.core.Handler;
import com.arangodb.shaded.vertx.core.buffer.Buffer;
import com.arangodb.shaded.vertx.core.parsetools.impl.JsonParserImpl;
import com.arangodb.shaded.vertx.core.streams.ReadStream;
/**
* A parser class which allows to incrementally parse json elements and emit json parse events instead of parsing a json
* element fully. This parser is convenient for parsing large json structures.
*
* The parser also parses concatenated json streams or line delimited json streams.
*
* The parser can also parse entire object or array when it is convenient, for instance a very large array
* of small objects can be parsed efficiently by handling array start/end and object
* events.
*
* Whenever the parser fails to parse or process the stream, the {@link #exceptionHandler(Handler)} is called with
* the cause of the failure and the current handling stops. After such event, the parser should not handle data
* anymore.
*
* @author Julien Viet
*/
@VertxGen
public interface JsonParser extends Handler, ReadStream {
/**
* Create a new {@code JsonParser} instance.
*/
static JsonParser newParser() {
return new JsonParserImpl(null);
}
/**
* Create a new {@code JsonParser} instance.
*/
static JsonParser newParser(ReadStream stream) {
return new JsonParserImpl(stream);
}
/**
* Handle a {@code Buffer}, pretty much like calling {@link #handle(Object)}.
*
* @return a reference to this, so the API can be used fluently
*/
@Fluent
JsonParser write(Buffer buffer);
/**
* End the stream, this must be called after all the json stream has been processed.
*/
void end();
/**
* Flip the parser to emit a stream of events for each new json object.
*
* @return a reference to this, so the API can be used fluently
*/
@Fluent
JsonParser objectEventMode();
/**
* Flip the parser to emit a single value event for each new json object.
*
* Json object currently streamed won't be affected.
*
* @return a reference to this, so the API can be used fluently
*/
@Fluent
JsonParser objectValueMode();
/**
* Flip the parser to emit a stream of events for each new json array.
*
* @return a reference to this, so the API can be used fluently
*/
@Fluent
JsonParser arrayEventMode();
/**
* Flip the parser to emit a single value event for each new json array.
*
* Json array currently streamed won't be affected.
*
* @return a reference to this, so the API can be used fluently
*/
@Fluent
JsonParser arrayValueMode();
@Override
JsonParser pause();
@Override
JsonParser resume();
@Override
JsonParser fetch(long amount);
@Fluent
JsonParser endHandler(Handler endHandler);
@Fluent
JsonParser handler(Handler handler);
@Fluent
JsonParser exceptionHandler(Handler handler);
}