JarCastingCommon handler for JSON libraries
Overview
This library provides a common handler interface to describe JSON documents for other JSON processing libraries.
Consult the documentation and the usage description for further information:
- Handling JSON documents
- Available JSON handlers
- Available users of JSON handlers
- Custom JSON handlers
- Using JSON handlers
Maven
This library is hosted in the Maven Central Repository. You can use it with the following coordinates:
<dependency>
<groupId>net.markenwerk</groupId>
<artifactId>utils-json-handler</artifactId>
<version>2.0.1</version>
</dependency>
Usage
Handling JSON documents
This library provides the JsonHandler interface which provides a collection of callback methods that can be called (e.g. by a JSON parser or by domain model for JSON documents) to describe a JSON document and calculates a result for the described JSON document.
Available JSON handlers
- A
AppendingJavaTextJsonHandlerfrom the JSON text handler library appends a text that mimics thetoString()behavior of Java collection classes and represents the described JSON document to anAppendable. - A
AppendingJsonTextJsonHandlerfrom the JSON text handler library appends a JSON text that represents the described JSON document to anAppendable. - A
JavaTextJsonHandlerfrom the JSON text handler library creates aStringcontaining a text that mimics thetoString()behavior of Java collection classes and represents the described JSON document. - A
JsonTextJsonHandlerfrom the JSON text handler library creates aStringcontaining a JSON text that represents the described JSON document. - A
JsonValueJsonHandlercreates aJsonValuethat represents the described JSON document. - A
NullJsonHandlerfrom this library is an empty implementation that does nothing. - A
RecordingJsonHandlerfrom the JSON replay handler library creates aJsonReplaycontaining a sequence ofJsonEventsthat represent the described JSON document. - A
XmlDocumentJsonHandlerfrom the JSON XML handler library creates a XMLDocumentthat represents the described JSON document.
Available users of JSON handlers
- A
JsonDocumentfrom the JSON domain model library uses aJsonHandlerto describe its rootJsonValue. - A
JsonPushParserfrom the fast JSON parser library uses aJsonHandlerto describe the parsed JSON document. - A
JsonReplayfrom the JSON replay handler library uses aJsonHandlerto describe the previously described JSON document.
Custom JSON handlers
A JSON document will be described to a JsonHandler by calls to the appropriate callback methods using the following rules:
- A JSON document will begin with
onDocumentBegin()and end withonDocumentEnd() - A JSON array will begin with
onArrayBegin()and end withonObjectEnd() - Elements of a JSON array will be added with either
onArrayBegin(),onObjectBegin(),onNull()onBoolean(boolean),onLong(long),onDouble(double)oronString(String). - If a JSON array has more than one element,
onNext()will be called between each two elements. - A JSON object will bebegin with
onObjectBegin()and end withonObjectEnd() - Entries of a JSON object will be added with
onName(String)followed by eiteronArrayBegin(),onObjectBegin(),onNull()onBoolean(boolean),onLong(long),onDouble(double)oronString(String). - If a JSON object has more than one entry,
onNext()will be called between each two entries.
All methods sholdn't throw any exceptions other than JsonHandlingException, except onDouble(double) and onString(String) which need to check the passed argument and therefore may throw a InvalidJsonValueException.
This library provides the IdleJsonhandler with empty callback methods and check methods to be used in onDouble(double) or onString(String), which simplifies the creation of custom implementations.
The following example JsonHandler counts the number of JSON literals in the described JSON document:
JsonHandler<Integer> jsonHandler = new IdleJsonHandler<Integer>(){
int result;
@Override
public void onNull() throws JsonHandlingException {
result++;
}
@Override
public void onBoolean(boolean value) throws JsonHandlingException {
result++;
}
@Override
public void onLong(long value) throws JsonHandlingException {
result++;
}
@Override
public void onDouble(double value) throws InvalidJsonValueException, JsonHandlingException {
checkDoubleValue(value);
result++;
}
@Override
public void onString(String value) throws InvalidJsonValueException, JsonHandlingException {
checkStringValue(value);
result++;
}
@Override
public Integer getResult() throws JsonHandlingException {
return result;
}
};
Using JSON handlers
To describe a JSON document it is necessary to call the appropriate callback methods using the following rules:
- A JSON document must be begun with
onDocumentBegin()and ended withonDocumentEnd() - A JSON array must be gegun with
onArrayBegin()and ended withonObjectEnd() - Elements of a JSON array must be added with either
onArrayBegin(),onObjectBegin(),onNull()onBoolean(boolean),onLong(long),onDouble(double)oronString(String). - If a JSON array has more than one element,
onNext()must be called between each two elements. - A JSON object must be gegun with
onObjectBegin()and ended withonObjectEnd() - Entries of a JSON object must be added with
onName(String)followed by eiteronArrayBegin(),onObjectBegin(),onNull()onBoolean(boolean),onLong(long),onDouble(double)oronString(String). - If a JSON object has more than one entry,
onNext()must be called between each two entries.
The following sequence of callback methods describes the example.json.
// a generic JsonHandler
JsonHandler<?> handler = ...
// begin a document
handler.onDocumentBegin();
// begin an object
handler.onObjectBegin();
// inside the object: set a name followed by a value to describe an entry
handler.onName("null");
handler.onNull();
// inside the object: call next between two entries
handler.onNext();
handler.onName("boolean");
handler.onBoolean(true);
handler.onNext();
handler.onName("long");
handler.onLong(-42);
handler.onNext();
handler.onName("double");
handler.onDouble(-23.42);
handler.onNext();
// begin an array
handler.onName("array");
handler.onArrayBegin();
// inside the object: just a value to describe an entry
handler.onString("foo");
// inside the object: call next between two entries
handler.onNext();
handler.onString("bar");
// end the array
handler.onArrayEnd();
// end the object
handler.onObjectEnd();
// end the document
handler.onDocumentEnd();
