Skip to content

Getting Started Guide

Jump to bottom
Bill Davidson edited this page Sep 27, 2016 · 34 revisions

You will need to have Apache Commons Logging. It's a logging facade so it works with other logging frameworks (the JUnit tests use Log4j2). For building and testing, it is included as a Maven dependency in the pom.xml as well as some other dependencies for JUnit testing.

Maven users should see the Maven Central Repository page for the release that you want for XML to add to your pom.xml to include JSONUtil as a dependency. The MCR supports some other dependency based build tools such as Gradle, Ivy, Grape and others and provides dependency configuration information for those as well.

Example dependencies in pom.xml for Maven users using the Java 8 version of JSONUtil

<dependency>
    <groupId>commons-logging</groupId>
    <artifactId>commons-logging</artifactId>
    <version>1.2</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>org.kopitubruk.util</groupId>
    <artifactId>JSONUtil</artifactId>
    <version>1.10.2</version>
    <scope>compile</scope>
</dependency>

If you are using Java 7, then the above version would be 1.10.2-java7. Java 6 and Java 5 are done similarly.

If you are not using Maven or another tool that downloads dependencies automatically, then you will have to download the jar file for the library and place it in your runtime classpath. The same goes for the JSONUtil jar file, which is available from the releases page. For webapps, the place to put these jars is typically in the webapp's /WEB-INF/lib directory.

The API page in the Javadoc for the JSONUtil class will tell you most of what you need to know. You send top level objects such as Maps to a static toJSON method and it returns a JSON string or writes JSON to an object that you provide that extends the abstract class java.io.Writer.

Basic Usage:
Integer x = 5;
int[] a = {1,1,2,3,5,8,13};
Map<String,Object> myData = new LinkedHashMap<>();
myData.put("x", x);
myData.put("a", a);
myData.put("bundle", ResourceBundle.getBundle("some.bundle.name", locale));
myData.put("status", "success");
String jsonStr = JSONUtil.toJSON(myData);

or if you prefer in a servlet to write the JSON output directly to the ServletResponse:

response.setHeader("Cache-Control", "no-cache");
response.setContentType("application/json; charset=UTF-8");
JSONUtil.toJSON(myData, response.getWriter());

Reflection is supported if you don't want to make maps. See Using Reflection to Encode Objects as JSON to learn how to configure JSONUtil use reflection to encode your objects with less effort on your part.

Configuration options are in JSONConfig, which is an optional configuration object to control validation and encoding options. Most of the time, most users will find that the defaults are adequate and they won't feel the need to create and pass a JSONConfig object.

Defaults for configuration options can be modified by using the JSONConfigDefaults class. Keep in mind that doing so will affect the defaults for all JSONConfig objects created in the same class loader, including those created by the JSONUtil.toJSON(...) methods that don't take a JSONConfig as an argument.

If you are running in a JEE web tier container (Tomcat, JBoss, Glassfish, etc.) you can permanently change most of the defaults using JNDI variables. See the JSONConfigDefaults class for more information. Most of the defaults can be viewed or modified at run time via a JMX MBean client as well.

There is an interface provided called JSONAble, which JSONUtil knows to use for objects that generate their own JSON.

The JSONParser class will parse JSON data. It converts Javascript objects to LinkedHashMap's with the property names being the keys. It converts Javascript arrays to ArrayList's. It is more permissive in the data that it accepts than the JSON standard. It allows Javascript strings with either type of quote. It allows unquoted identifiers. It allows full Javascript numbers. It also allows ECMAScript 6 style code point escapes. This parser should never be used as a JSON validator due to this permissiveness.

Error messages in exceptions and log messages are internationalized, though the only localizations available are currently English (default) and Spanish. If you would like to submit other localizations or correct my poor Spanish, please submit an issue for this project.

Clone this wiki locally