Common 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 AppendingJavaTextJsonHandler from the JSON text handler library appends a text that mimics the toString() behavior of Java collection classes and represents the described JSON document to an Appendable.
• A AppendingJsonTextJsonHandler from the JSON text handler library appends a JSON text that represents the described JSON document to an Appendable.
• A JavaTextJsonHandler from the JSON text handler library creates a String containing a text that mimics the toString() behavior of Java collection classes and represents the described JSON document.
• A JsonTextJsonHandler from the JSON text handler library creates a String containing a JSON text that represents the described JSON document.
• A JsonValueJsonHandler creates a JsonValue that represents the described JSON document.
• A NullJsonHandler from this library is an empty implementation that does nothing.
• A RecordingJsonHandler from the JSON replay handler library creates a JsonReplay containing a sequence of JsonEvents that represent the described JSON document.
• A XmlDocumentJsonHandler from the JSON XML handler library creates a XML Document that represents the described JSON document.

Available users of JSON handlers

• A JsonDocument from the JSON domain model library uses a JsonHandler to describe its root JsonValue.
• A JsonPushParser from the fast JSON parser library uses a JsonHandler to describe the parsed JSON document.
• A JsonReplay from the JSON replay handler library uses a JsonHandler to 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 with onDocumentEnd()
• A JSON array will begin with onArrayBegin() and end with onObjectEnd()
• Elements of a JSON array will be added with either onArrayBegin(), onObjectBegin(), onNull() onBoolean(boolean), onLong(long), onDouble(double) or onString(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 with onObjectEnd()
• Entries of a JSON object will be added with onName(String) followed by eiter onArrayBegin(), onObjectBegin(), onNull() onBoolean(boolean), onLong(long), onDouble(double) or onString(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 with onDocumentEnd()
• A JSON array must be gegun with onArrayBegin() and ended with onObjectEnd()
• Elements of a JSON array must be added with either onArrayBegin(), onObjectBegin(), onNull() onBoolean(boolean), onLong(long), onDouble(double) or onString(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 with onObjectEnd()
• Entries of a JSON object must be added with onName(String) followed by eiter onArrayBegin(), onObjectBegin(), onNull() onBoolean(boolean), onLong(long), onDouble(double) or onString(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();