Package org.openntf.jsonbeanx

The JsonBeanX classes can be used by IBM Notes/Domino XPages developers to convert between JSON strings and Java beans.

See:
Description

Class Summary

J2BConverter	The J2BConverter class can do the following:
J2BSettings	Settings used by J2BConverter when you are converting between JSON strings and Java beans.

Exception Summary

J2BException

An Exception thrown by the J2BConverter.

Package org.openntf.jsonbeanx Description

The JsonBeanX classes can be used by IBM Notes/Domino XPages developers to convert between JSON strings and Java beans. It uses the IBM Commons JsonParser to do part of the conversion, so if you want to use this outside of an XPages environment you must include the com.ibm.commons library with your project to use the com.ibm.commons.util.io.json classes.

By default, the JSON parser can read JSON strings and output Lists and Maps, and it can take Lists and Maps and convert them to JSON. The JsonBeanX library allows you to convert JSON directly to a Java bean, or a Java bean directly to JSON.

Some ground rules:

• Your Java bean must be a public class, and it must have a public, no-arg constructor (like public MyBean(){})

• Your Java bean must have setters that match each JSON field you want to import (cost and setCost(int i)) and a matching getter for each JSON field you want to write (getCost() and cost). You can override field-to-method mappings using J2BSettings, but if you have control of the beans it's easier just to make the fields and getters/setters match.

• By default, Eclipse will generate a getter field starting with "is" for boolean values. These methods will be skipped by J2BConverter. Only fields that begin with "get" or "set" are used. If you have boolean values in your bean, make sure there are corresponding "get" methods for them, or use addMethodMapping to map the "is" method to a JSON field.

• Try not to use JavaScript reserved words or common method names (length, split, etc.) as field names. Those can work as JSON fields, but they make it more difficult to use the resulting JSON in JavaScript.

• Be careful using float or Float values. Those are prone to conversion errors going from Java to JSON. For example, a float value of 5.6 in Java will result in a JSON value of 5.599999904632568. You should use double/Double values instead.

• Field types that are allowed in your Java beans:
• primitives (int, long, etc.)
• Number types (Integer, Long, etc.)
• String
• Date (the java.util kind)
• Arrays of any of the types above (int[], String[], etc.)
• List and its subclasses. It's usually a good idea to strongly type your lists (List<String>, etc.). It helps with the conversion of JSON values to List items because we know how to cast.
• Custom bean classes of your own.
• Field types that are NOT allowed in your Java beans:
• Interfaces (other than List), because the converter has no way of knowing how to create a new instance.
• Java classes that are not beans (and not mentioned above).
• Maps can work but they're kind of sketchy, because the JsonParser can't really tell the difference between a Map and an Object. Avoid them unless they're really necessary, and if you do use them make sure they are strongly typed (Map<String, Integer>, etc.).
• When you use generics to type your Lists and Maps, don't use generics wildcards like List<?> or List<? extends Foo>. Stick to the field types mentioned above.

Converting JSON to Java Beans

Given the following JSON:

{ "title":"Gone With The Breeze", 
  "studio":"NGN",
  "awards": ["Best Picture","Best Actress","Best Actor"],
  "revenue": {"unadjusted":200000000,"adjusted":1750000000},
  "lastUpdated":"2016-01-12",
  "year":1939
 }

We can map this to the following two Java bean classes:

public class Movie {
	String title;
	String studio;
	String[] awards;
	Revenue revenue; 
	String lastUpdated;
	int year;

	public Movie() {}
 	public String getTitle() { return this.title; }
 	public void setTitle(String title) { this.title = title; }
 	public String getStudio() { return this.studio; }
 	public void setStudio(String studio) { this.studio = studio; }
 	public String[] getAwards() { return this.awards; }
 	public void setAwards(String[] awards) { this.awards = awards; }
 	public Revenue getRevenue() { return this.revenue; }
 	public void setRevenue(Revenue revenue) { this.revenue = revenue; }
 	public String getLastUpdated() { return this.lastUpdated; }
 	public void setLastUpdated(Date lastUpdated) { this.lastUpdated = lastUpdated; }
 	public int getYear() { return this.year; }
 	public void setYear(int year) { this.year = year; }
}

and

public class Revenue {
	long unadjusted;
	long adjusted;

	public Revenue() {}
	public long getUnadjusted() { return this.unadjusted; }
 	public void setUnadjusted(long unadjusted) { this.unadjusted = unadjusted; }
 	public long getAdjusted() { return this.adjusted; }
 	public void setAdjusted(long adjusted) { this.adjusted = adjusted; }
 }

This is easily done using the following code:

List<Movie> movies = J2BConverter.jsonToBean(Movie.class, json);

However, in this case the date format won't map correctly. Dates in JSON are always Strings (there is no JSON date type), so you need to write this additional code:

J2BSettings settings = new J2BSettings();
settings.setDateFormat("yyyy-MM-dd");
List<Movie> movies = J2BConverter.jsonToBean(Movie.class, json, settings);

Sometimes JSON will include a prefix before class data, like this:

{"movie": {"title":"Gone With The Breeze", 
  "studio":"NGN",
  "awards": ["Best Picture","Best Actress","Best Actor"],
  "revenue": {"unadjusted":200000000,"adjusted":1750000000},
  "lastUpdated":"2016-01-12",
  "year":1939
 }}

In this case you would need to either use a wrapper for Movie.class like this:

public class MovieWrapper {
	Movie movie;

	public MovieWrapper() {}
	public Movie getMovie() { return this.movie; }
 	public void setMovie(Movie movie) { this.movie = movie; }
 }

and call jsonToBean(MovieWrapper.class, json, settings), or you would need to specify a classname prefix for Movie.class like this:

J2BSettings settings = new J2BSettings();
settings.setDateFormat("yyyy-MM-dd");
settings.addJSONClassPrefix(Movie.class, "movie");
List<Movie> movies = J2BConverter.jsonToBean(Movie.class, json, settings);

A few other things:

• jsonToBean always returns data as a List, even if there is only one object created.
• jsonToBean will throw a J2BException if the JSON is null, or "", or it cannot be parsed.
• jsonToBean will return an empty List (size==0) if the JSON is "[]" or "{}".
• If you parse JSON that contains key/value pairs that do not map to anything in your bean (like {"foo": "bar"}), jsonToBean will return a List with a single bean object that contains default data. If you would rather have the converter throw an Exception in the case that the JSON is not relevant to your bean, please use setMappingFailureFatal and/or addRequiredField.

Converting Java Beans to JSON

To convert a Java bean to JSON, do the following:

J2BSettings settings = new J2BSettings();
settings.setDateFormat("yyyy-MM-dd");
String json = J2BConverter.beanToJson(movie, settings);

The J2BSettings parameter is optional; in this case we need it because of the Date value. By default it will output the date in the system format, which might not be what you want.

Take special note of settings that can cause parsing to fail if certain conditions are not met: setMappingFailureFatal and addRequiredField. These can be very useful for JSON validation because they will cause beanToJson to throw an Exception if JSON fields cannot be mapped or if specific JSON fields are not present.

Creating Stub Class Code

createStubClasses can also suggest a Java bean class structure for you based on a JSON string, if you need to parse some JSON you have never used before. For the JSON example above, a call to:

String javaBeanSuggestion = J2BConverter.createStubClasses(json);

results in the following:

public class Revenue {
	Double unadjusted; 	// 2.0E8
	Double adjusted; 	// 1.75E9

	public Revenue() {}
	public Double getUnadjusted() { return this.unadjusted; }
 	public void setUnadjusted(Double unadjusted) { this.unadjusted = unadjusted; }
 	public Double getAdjusted() { return this.adjusted; }
 	public void setAdjusted(Double adjusted) { this.adjusted = adjusted; }
 }

public class JsonData {
	String studio; 	// NGN
	List<String> awards; 	// [Best Picture, Best Actress, Best Actor]
	String title; 	// Gone With The Breeze
	Revenue revenue; 
	Double year; 	// 1939.0
	String lastUpdated; 	// 2016-01-14

	public JsonData() {}
 	public String getStudio() { return this.studio; }
 	public void setStudio(String studio) { this.studio = studio; }
 	public List<String> getAwards() { return this.awards; }
 	public void setAwards(List<String> awards) { this.awards = awards; }
 	public String getTitle() { return this.title; }
 	public void setTitle(String title) { this.title = title; }
 	public Revenue getRevenue() { return this.revenue; }
 	public void setRevenue(Revenue revenue) { this.revenue = revenue; }
 	public Double getYear() { return this.year; }
 	public void setYear(Double year) { this.year = year; }
 	public String getLastUpdated() { return this.lastUpdated; }
 	public void setLastUpdated(Date lastUpdated) { this.lastUpdated = lastUpdated; }
 }

Items of note:

• all number values are expressed as Doubles, because that's what the JsonParser returns them as
• the Date value is expressed as a String ,because JSON dates are indeed Strings
• the "awards" value that was a String[] in our original bean is expressed as a List<String>, because those are represented the same in JSON

You can adjust those items as needed or leave them as-is.

Also, the class fields have comments indicating what the data looked like when it was parsed, so you can make a better guess at what the field types should be.

createStubClasses isn't perfect, but it will help get you started. Specifically, if it encounters a List of JSON objects and the objects in the list have different structures, only the first object in the list will be used for class generation, and if multiple instances of the same nested class are encountered they will be output multiple times. So please check the results and don't use them blindly.

Normally you want to copy all the stub classes into separate class files for use by your code. If you decide you want to copy them into an existing class as inner classes, that will work but only if you make them static inner classes. Inner classes that aren't static cannot be instantiated directly from outside their parent class, and the J2BConverter won't be able to use them.

Why Use This Instead of GSON or Jackson?

The gson and Jackson libraries will also do this sort of JSON-to-bean mapping, and they are much more "complete" in terms of options and support. So why use this library?

The advantages of JsonBeanX are:

• it's small
• it's very easy to use
• if you have a problem you can probably find and fix it in the source (because it's small, and I didn't go crazy with interfaces, architecture, etc.)
• you don't have to work around security exceptions in XPages like you do with gson and Jackson

It's up to you though. Options are good.

Copyright (C) 2015-16 Julian Robichaux

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.