北野

Overview of Date and Calendar classes

TOML stands for Tom’s Own Minimal Language. It is a configuration language vaguely similar to YAML or property lists, but far, far better. But before we get into it in detail, let’s look back at what came before.

Long Ago, In A Galaxy Far, Far Away

Since the beginning of computing, people have needed a way to configure their software. On Linux, this generally is done in text files. For simple configurations, good old foo = bar works pretty well. One setting per line, name on the left, value on the right, separated by an equals. Great. But when your configuration gets more complicated, this quickly breaks down. What if you need a value that is more than one line? How do you indicate a value should be parsed as a number instead of a string? How do you namespace related configuration values so you don’t need ridiculously long names to prevent collisions?

The Dark Ages

In the 90’s, we used XML. And it sucked. XML is verbose, it’s hard for humans to read and write, and it still doesn’t solve a lot of the problems above (like how to specify the type of a value). In addition, the XML spec is huge, processing is very complicated, and all the extra features invite abuse and overcomplication.

Overview of Date and Calendar classes

In this tutorial we look at the classes in java that are helpful in manipulating dates. Manipulating dates in java can be challenging, especially if you are building applications that cater to multiple timezones. Parsing dates, printing a date in UTC, printing a date in a different timezone, comparing dates, adding time to date… we will be looking at all of these in this tutorial. We first begin with the introduction to the classes and then follow up with examples. You may want to directly jump to the examples, however, we strongly recommend that you understand the classes first, since that will make the examples very easy to understand.

• java.util.Date - This class is used to represent a specific time with a precision of millisecond. If you create a new Date object, it obtains the current system time using System.currentTimeMillis(). This is the number of milliseconds since epoch time (midnight, January 1, 1970 UTC). Here’s the tricky part, date stores time as number of seconds since epoch, it is a UTC time. However, when you print the date, you get the string representation of the date in the local timezone. Also note that the Date class is not designed to manipulate hour, month, year etc or retrieve them. Use this class only to create data or compare two dates. For all other uses, see the Calendar or GregorianCalendar class.

• java.util.Calendar - Calendar class allows manipulating data using its various fields such as minute, hour, day etc. As in the java.util.Date object, time is represented as number of milliseconds since epoch time. To get an instance of the Calendar use the Calendar.getInstance() method which returns a locale sensitive Calendar instance. Various set and get methods can be used to set and get time values. The current time is represented in two ways - 1. as number of milliseconds since epoch and 2. as local fields such as YEAR, MONTH, DAY, HOUR, MINUTE etc. The conversion between the two types is achieved by using the timezone offset (getOffset()) and the daylight savings fields.
  the MONTH fields starts from 0 (JANUARY).
  The DAY_OF_MONTH starts from 1
  the DAY_OF_WEEK starts from SUNDAY with a value of 1.
  HOUR starts from 0

• java.util.GregorialCalendar - A GregorianCalendar is the default implementation of the Abstract Calendar class. Next let us look at examples

Overview of The API Classes

org.json has classes to parse and write json string. It also converts between json and xml, HTTP header, Cookies, and CDF. The main classes are:

1. org.json.JSONObject - This class stores unordered key value pairs. The value can be Boolean, JSONArray, Number, String or JSONObject.NULL. It has constructors to take in a json string and store it as key value pairs. It also has constructors that take in a Map, a bean or a String
2. org.json.JSONTokener - This class parses a JSON string and is also used internally by the JSONObject and JSONArray classes to parse JSON Strings
3. org.json.JSONArray - This class stores an ordered sequence of values. Externally it represents a JSON Array
4. org.json.JSONWriter - This class represents method to produce json text. It has an append(String) method to append a string to a json text, key(String) and value(String) method to add key and values to json string. It can also write an array.
5. org.json.CDL- This class has methods to convert comma delimited text to JSONArray and a JSONArray to a comma delimited text. The array contains rows of comma separed strings, with rows separated by newline. The first row contains names.
6. org.json.Cookie - This class has method to convert a web browser cookie to a JSONObject and back.
7. org.json.CookieList - This class has method to convert a list of cookies to JSONObject and back. Lets see some examples

Parse JSON

This examples shows how to parse a JSON string. The JSON string in this example is a list of genres (limited to 2) from freemusicarchive.org

Json Simple is, as the name suggest, a very simple API. The API itself is made up of around 13 classes. The main classes are :

• JSONParser - This parses Json text. It takes in a java.io.Reader or a String Object. It is also possible to pass a ContentHandler or ContainerHandler to the parser.
• JSONObject - This is a java representation of JSON string. It stores key value pairs. JsonObject extends HashMap. It has method to encode a map to a JSON text (writeJSONString(Map map, Writer out))
• JSONArray - Represents a collection. It extends an ArrayList. It implements the JSONAware and JSONStreamAware interface
• JSONValue - This class has methods to parse JSON string into Java objects. It uses the JSONParser to do so. It has methods to write JSON string from many java types (writeJSONString(Object value, Writer out)). It also has methods to escapte special characters using the escape(String s) method. This method escapes quotes, , /, \r, \n, \b, \f, \t and other control characters (U+0000 through U+001F)
• JSONAware - Beans that support output to JSON form should implement this interface. Lets see some examples

Parse JSON

This examples shows how to parse a JSON string. The JSON string in this example is a list of genres (limited to 2) from freemusicarchive.org

1. Overview
2. Goals for Gson
3. Gson Performance and Scalability
4. Gson Users
5. Using Gson

• Using Gson with Maven
• Primitives Examples
• Object Examples
• Finer Points with Objects
• Nested Classes (including Inner Classes)
• Array Examples
• Collections Examples
• Collections Limitations
• Serializing and Deserializing Generic Types
• Serializing and Deserializing Collection with Objects of Arbitrary Types
• Built-in Serializers and Deserializers
• Custom Serialization and Deserialization
• Writing a Serializer
• Writing a Deserializer

In this tutorial we look at how to selectively include fields from a java object to a json string. By default, Gson tries to map all fields in the java object to the corresponding property in json. However, in certain cases we may want to control that. There are a few ways to do this. It is also possible to excluse fields from third party packages where we have no access to the source code. The different ways to exclude fields are :

1. By defining a custom annotation and ignoring fields that are annotated with that.
2. By Defining a custom exclusion class by extending the ExclusionStrategy interface and implementing the public boolean shouldSkipField(FieldAttributes f); and public boolean shouldSkipClass(Class clazz); methods
3. By using the @Expose annotations and then using the excludeFieldsWithoutExposeAnnotation() method on the GsonBuilder. This will ignore all fields except the ones that have been exposed using the @Expose annotation.

Just as we saw in the previous tutorial, Gson provides way to specify custom serializers and deserializers. Register a custom serializer with the GsonBuilder if you need you own way to convert a java object to json and you a custom deserializer if you dont like Gson’s way of converting json to the java object. The first example below shows a custom serializer and the second example shows a custom deserializer.

Custom Serializer

Create a custom serializer by implementing a com.studytrails.json.gson.JsonSerializer and implementing the public JsonElement serialize(T src, Type typeOfSrc, JsonSerializationContext context); method. src is the source object and Type is the type of the source object. The example below demonstrates a custom Serializer.

In the earlier tutorials we have seen how gson can serialize and deserialize java classes with or without hierarchies. By default, it introspects the classes and comes with with a strategy for serializing and deserializing it. However, in some cases, you want to specify your own conversion strategy. That is, you want to control how the java object is converted to json string and the other way round. Gson provides a capability to specify a custom type adapter. You tell Gson that for a particular class, use the conversion strategy specified by your custom adapter. Lets look at how to write the type adapter : To write a custom adapter extend the com.google.gson.TypeAdapter abstract class. Implement the public abstract T read(JsonReader in) throws IOException; and public abstract void write(JsonWriter out, T value) throws IOException; methods. The adapter should also handle nulls. Create the Type adapter instance and then register it with the GsonBuilder. Create the Gson object from the GsonBuilder and then use that to serialize and deserialize. Lets look at an example

package com.studytrails.json.gson;

import java.io.IOException;
import java.net.MalformedURLException;
import java.net.URL;

import org.apache.commons.io.IOUtils;

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class DatasetTypeAdapterExample8 {

	public static void main(String[] args) throws MalformedURLException, IOException {
		String url = "http://freemusicarchive.org/api/get/albums.json?api_key=60BLHNQCAOUFPIBZ&limit=5";
		String json = IOUtils.toString(new URL(url));
		// Create the custom type adapter and register it with the GsonBuilder
		// class.
		Gson gson = new GsonBuilder().registerTypeAdapter(Dataset.class, new DatasetTypeAdapter()).create();
		// deserialize the json to Albums class. The Dataset objects are part of
		// the Albums class. Whenever Gson encounters an object of type DataSet
		// it calls the DatasetTypeAdapter to read and write json.
		Albums albums = gson.fromJson(json, Albums.class);
		System.out.println(albums.getDataset()[1].getAlbum_title());
		// prints
		// http://freemusicarchive.org/music/The_Yes_Sirs/Through_The_Cracks_Mix_Vol_1/
	}
}

Serializing inner classes

Gson can serialize inner classes and static nested classes. The detailed example below demonstrates the following things.

1. Serializing class containing static nested class
2. Serializing class containing non static nested class (Inner class)
3. De-serializing json to a class containing static and non static inner class
4. Serializing static nested class (without the enclosing type)
5. Serializing non static nested class (without the enclosing type)
6. De-serializing json to a static nested class (without the enclosing type)
7. De-serializing json to a non static nested class (without the enclosing type)