Tutorials     About     RSS
Tech and Media Labs

RionObjectWriter

Jakob Jenkov
Last update: 2020-05-22

The RION Ops RionObjectWriter class makes it easy to write Java objects as a RION field to a byte array. In other words, the RionObjectWriter can serialize Java objects to RION. In this Java RionObjectWriter tutorial we will take a closer look at how to use the RionObjectWriter in RION Ops for Java.

Create a RionObjectWriter

To use the RionObjectWriter you must first create an instance of the RionObjectWriter class, com.nanosai.rionops.rion.object.RionObjectWriter. The easiest way to create a RionObjectWriter instance is via the RionObjectWriterBuilder class. Here is an example of using a RionObjectWriterBuilder to create a RionObjectWriter instance:

RionObjectWriterBuilder writerBuilder = new RionObjectWriterBuilder();
writerBuilder.addDeclaredFields(Pojo.class);

RionObjectWriter rionObjectWriter = writerBuilder.build();

The RionObjectWriterBuilder is designed for "method chaining", so the above example can be written a bit more densely:

RionObjectWriter writer =
        new RionObjectWriterBuilder().addDeclaredFields(Pojo.class).build();

These examples build a RionObjectWriter which will serialize all fields (private, protected, default and public) found in the Pojo class to RION. The RionObjectWriterBuilder inspects the Pojo Class via Java Reflection to see what fields it contains, and create field writers for each of the fields.

Once created, the RionObjectWriter instance then only serialize objects of the given class. To serialize objects of multiple classes you will have to create a RionObjectWriter for each class.

Note: You only need one RionObjectWriter per root class you want to serialize. If a given class represents an object graph consisting of other classes referenced from within the root class (or any of its field's classes recursively), all of these classes will be serialized too.

To elaborate, in the example above, if the Pojo class contained fields of class Pojo2 and Pojo3 internally, these would be serialized too because they are part of an object graph rooted by a Pojo object. But the RionObjectWriter created in the example above could not serialize a Pojo2 or Pojo3 directly - as root of an object graph. For that you would have to create a separate RionObjectWriter for each of Pojo2 and Pojo3.

Write Object

The RionObjectWriter is capable of writing both acyclic and cyclic object graphs. The RionObjectWriter contains an writeAcyclic() and writeCyclic() method for these purposes. Writing an acyclic object graph is simpler than writing an acyclic object graph. That is why the processes have been separated into two different methods - to avoid the extra work required during cyclic object graph serialization if you know you are writing an acyclic object graph. Both of these methods will be described in more detail in later sections.

An acyclic object graph is an object graph where each object in the graph is only referenced by one other object. A cyclic object graph is an object graph where objects can be referenced by more than one other object in the graph. The graph can even be truly cyclic, meaning you can cycle around in the graph from object to object indefinitely. The RionObjectWriter can still serialize it.

writeAcyclic()

The RionObjectWriter writeAcyclic() can write an acyclic object graph as RION into a byte array. If the object is part of a cyclic (not acyclic) object graph, the writeAcyclic() method will enter an infinite recursion and eventually crash. Here is an example of writing an object using the RionObjectWriter writeAcyclic() method:

Pojo pojo = new Pojo();
pojo.setId(999);
pojo.setName("Pojo 1");

byte[] dest = new byte[128];

RionObjectWriterBuilder writerBuilder = new RionObjectWriterBuilder();
writerBuilder.addDeclaredFields(Pojo.class);

RionObjectWriter rionObjectWriter = writerBuilder.build();

int bytesWritten = rionObjectWriter.writeAcyclic(pojo, 1, dest, 0);

The bytesWritten variable will contain the value 20 after running this code, as the serialized Pojo object takes 20 bytes to represent as RION.

Notice how the writeAcyclic() method takes 4 parameters. The first parameter is the object to write.

The second parameter is the maximum number of length bytes the serialized RION Object field will need. For instance, if the total length of the serialized RION is 255 (2^8 -1) bytes or less, 1 length byte required. If the RION length is 65535 (2^16 -1) bytes or less, 2 length bytes are required etc.

The third parameter is the byte array (destination) into which the serialized RION should be written. The fourth parameter is the offset into the destination array to start writing the RION data.

The serialized RION looks like this (in hexadecimal notation):

C1 12                (Object)
    E2 6964          (Key Short: id)
    22 03E7          (Int64Pos: 999)
    E4 6E616D65      (Key Short: name)
    66 506F6A6F2031  (UTF Short: Pojo 1)

writeCyclic()

The RionObjectWriter writeCyclic() method can write a cyclic object graph as RION to a byte array. Here is an example of writing a cyclic object graph to RION using the RionObjectWriter writeCyclic() method. Please imagine that the Pojo object represents a cyclic object graph - and not a single object (as is actually the case in the code below). I will update the example

Pojo pojo = new Pojo();

byte[] dest = new byte[128];

RionObjectWriterBuilder writerBuilder = new RionObjectWriterBuilder();
writerBuilder.addDeclaredFields(Pojo.class);

RionObjectWriter rionObjectWriter = writerBuilder.build();

int bytesWritten = rionObjectWriter.writeCyclic(pojo, 1, dest, 0);

The bytesWritten variable will contain the value 20 after running this code, as the serialized Pojo object takes 20 bytes to represent as RION.

Notice how the writeAcyclic() method takes 4 parameters. The first parameter is the object to write.

The second parameter is the maximum number of length bytes the serialized RION Object field will need. For instance, if the total length of the serialized RION is 255 (2^8 -1) bytes or less, 1 length byte required. If the RION length is 65535 (2^16 -1) bytes or less, 2 length bytes are required etc.

The third parameter is the byte array (destination) into which the serialized RION should be written. The fourth parameter is the offset into the destination array to start writing the RION data.

Jakob Jenkov

Featured Videos

Close TOC

All Trails

Trail TOC

Page TOC

Previous

Next