Common handler for JSON processing libraries for Java
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
.gitignore
.travis.yml
LICENSE
README.MD
pom.xml

README.MD

Common handler for JSON libraries

Build Status Coverage Status Dependency Status Maven Central Issues MIT License

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:

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

Available users of JSON handlers

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();