Tutorials     About     RSS
Tech and Media Labs


Jakob Jenkov
Last update: 2017-03-08

The IonObjectReader (com.nanosai.gridops.ion.read.IonObjectReader) can be used to read ION data into Java objects. The IonObjectReader uses Java Reflection to inspect the object's class so it can read the ION fields into the corresponding object fields.

Using the IonObjectReader to read objects does not perform as well as using the IonReader directly, but it is much easier to use.

Creating an IonObjectReader

You create an IonObjectReader like this:

IonObjectReader reader = new IonObjectReader(MyClass.class);

As you can see the IonObjectReader takes the class of the object it should read as a parameter to its constructor. The created IonObjectReader can only read objects of this class. If you need to read objects of different classes, create one IonObjectReader instance for each class.

What happens inside the IonObjectReader constructor is pretty expensive so you should reuse IonObjectReader instances as much as possible.

The IonObjectReader is not thread safe, so you should not share it across threads. Only within the same thread.

Reading Objects

Reading an objet using the IonObjectReader is done using the readObject() method. Here is an example of reading an object with the IonObjectReader readObject() method:

byte[] source = ... // source byte array with ION data.
int sourceOffset = 0;
IonObjectReader reader = new IonObjectReader(MyClass.class);
MyClass myClass = (MyClass) reader.readObject(source, sourceOffset);

The readObject() method takes the source byte array where the ION Object to read is located, as well as an offset to where in the byte array it is located, as parameters.

Notice the cast to MyClass of the objet returned by the IonObjectReader. For now this is necessary, but we expect to be able to get rid of that with Java Generics. We have just started focusing on the bare essentials.

The IonObjectReader Uses the Fields of a Class

The IonObjectReader uses Java reflection to see what fields the target class has. It is these fields that are read from the ION data, provided matching field names are found in the ION data. The IonObjectReader will read all matched fields regardless of whether they are private or transient in the target class. The fields are accessed directly. Setter methods are ignored.

When read the fields of an object the IonObjectReader will match the ION Key fields inside the corresponding ION Object to the field names of the target class. Fields in the ION data that does not have a matching field name in the target class are simple ignored.

If you want to exclude fields from deserialization, or match different ION Key values with the fields of the target class, you can use an IIonObjectReaderConfigurator instance. See next section for details.

Configuring the IonObjectReader

The IonObjectReader has a constructor which which can take an extra IIonObjectReaderConfigurator instance as parameter. This IIonObjectReaderConfigurator instance can configure the IonObjectReader instance.

Here is how calling the IonObjectReader constructor with an anonymous implementation of the IIonObjectReaderConfigurator looks:

IIonObjectReaderConfigurator configurator = new IIonObjectReaderConfigurator() {
    public void configure(IonFieldReaderConfiguration config) {


IonObjectReader reader = new IonObjectReader(MyClass.class, configurator);

The IIonObjectReaderConfigurator interface only contains a single method named configure(). This method is called by the IonObjectReader constructor one time per field in the target class.

Inside the configure() method you can set the configuration for the given field. The IonFieldReaderConfiguration object contains the configuration of a single field. The IonFieldReaderConfiguration object contains the following fields:

Field   field
String  fieldName
String  alias
boolean include

The field and fieldName properties are already filled in. The field property contains the java.lang.reflect.Field instance representing the field you can configure. The fieldName contains the name of the field which is the same value as you can obtain from calling field.getName() .

The alias property is null when configure() is called. If you set a new String value for alias, the IonObjectReader will match that property name in the ION data (ION Key fields to be specific) with the corresponding field.This is useful if the ION data uses a different field name for that field than your Java class.

The include property is true when configure() is called, meaning that the given field will be read by this IonObjectReader instance. If you set include to false then the corresponding field will not be read, even if a matching field is present in the ION data.

Here is an example that sets a new alias for one property and exclude another:

IIonObjectReaderConfigurator configurator = new IIonObjectReaderConfigurator() {
    public void configure(IonFieldReaderConfiguration config) {
        if("firstName".equals(config.fieldName)) {
            config.alias = "name";
        if("lastName".equals(config.fieldName)) {
            config.include = false;


IonObjectReader reader = new IonObjectReader(MyClass.class, configurator);

Jakob Jenkov

Featured Videos

Thread Congestion in Java - Video Tutorial

Sponsored Ads

Maildroppa - Smart Email Marketing Solution
Close TOC

All Trails

Trail TOC

Page TOC