Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/elasticpath/json-unmarshaller


https://github.com/elasticpath/json-unmarshaller

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

        
[![Build Status](https://api.travis-ci.org/elasticpath/json-unmarshaller.png)](https://travis-ci.org/elasticpath/json-unmarshaller)



# Elastic Path's JSON Unmarshaller



Elastic Path's JSON Unmarshaller is an extension to the popular [Jackson library](https://github.com/FasterXML/jackson). It provides annotation 

based unmarshalling of deep JSON object graphs into shallow POJOs using JsonPath. JsonPath is a very similar concept to XPath but for JSON. 

This library makes use of [Jway's](https://github.com/jayway/JsonPath) Java implementation of JsonPath. 



This library introduces a field annotation, @JsonPath, which can be used to specify JsonPath unmarshalling instructions in Java classes. @JsonPath

 annotations can be used exclusively, or in conjunction with Jackson's field-matching and @JsonProperty annotations. JsonPath annotations are in

 no-way mandatory and existing Jackson-annotated classes will function in this library without modification.



The below image shows how Jackson's field-matching and @JsonProperty annotations can be combined with @JsonPath annotations to unmarshal 

a single JSON object graph into two very different POJO arrangements. 

 

![alt text](https://cloud.githubusercontent.com/assets/868640/6225115/ae7be7b2-b63a-11e4-9d76-a23227bf82d3.png "Sample Unmarshalling")



Notice in the above image how the tree hierarchy can be re-arranged by using absolute JsonPath declarations `$.absolute.path.from.root` 

rather than relative `@.relative.path.from.parent`. At Elastic Path we find this flexibility invaluable when interacting with our Commerce 

REST API Cortex. Cortex is a Level 3 REST API which has support for following links server-side. Heavy use of server-side link following often 

results in large JSON trees being returned for a single REST request. Elastic Path's JSON Unmarshaller can easily manipulate these trees into 

whatever POJO arrangements are required.



## Usage

Json-unmarshaller is available at the Central Maven Repository. Maven users add this to your POM.



```xml



	com.elasticpath.json

	json-unmarshaller

    1.0.0



```  

### Configuration

* Build desired Java Class Hierarchy using @JsonPath and @JsonProperty annotations

```

public class Cart {

	@JsonPath("$._lineitems[0]._element")

	private List lineItems;

	@JsonPath("$.total-quantity")

	private int totalQuantity;

	@JsonProperty("postal-code")

    private String postalCode;

}

```

* Instantiate the unmarshaller, either with the default constructor, or using a custom Jackson ObjectMapper.

```

JsonUnmarshaller jsonUnmarshaller = new JsonUnmarshaller();

```

* Unmarshal the JSON into an instance of the desired class 

``` 

Cart cartPojo = jsonUnmarshaller.unmarshal(Cart.class, jsonString) 

``` 



Please see the test directory of this project for sample use cases, and the [Jway docs](https://github.com/jayway/JsonPath/blob/master/README.md#operators) 

for more complicated JsonPath arrangements.



## Error Handling

In the default implementation, unmarshalling is attempted for all fields in the class hierarchy regardless of errors. When no match is found 

for a field, or the annotation on a field contains syntax errors, the error will be logged and that field is simply left unset. Validation of 

 annotations should be done at compile time using the provided annotation verification class, which is described below.



## Annotation Verification

This project provides a convenience class for testing the validity of all supplied field annotations in a directory. In a maven build, the

exec-maven-plugin can easily be configured to verify all defined annotations at compile time as follows:

```xml



	org.codehaus.mojo

	exec-maven-plugin

	1.3.2

	

		

			check-json-annotations

			compile

			

				java

			

		

	

	

		true

		true

		com.fasterxml.jackson.contrib.jsonpath.annotation.AnnotationVerifier

		-1

		

			${project.basedir}/src/main/java/com/elasticpath/

		

	



```

## Source

Built with Java 7 and Maven:

run `mvn clean install` to build



## Unit Tests

* Test json data can be found in `src/test/resources`

* Test pojo classes can be found in `src/test/java/com/fasterxml/jackson/contrib/jsonpath/data`