JActor

Download JActor-4.5.0.zip and JID-2.0.4.zip from here. (The versions will change--the current versions are 4.5.0 and 2.0.4.) Then extract the JActor-4.5.0.jar and JID-2.0.4.jar files and copy them to a directory, GettingJidStarted. You will also need some slf4j jar files.

The j.bat file can be used to compile and run a test with the following command:

j className

The test is comprised of a single file in the GettingJidStarted directory, GettingStarted.jave, with a single method, main.

import org.agilewiki.jactor.factory.JAFactory;

import org.agilewiki.jid.JidFactories;

import org.agilewiki.jid.scalar.vlens.actor.RootJid;

import org.agilewiki.jid.scalar.vlens.string.StringJid;

public class GettingStarted {

public static void main(String[] args) throws Exception {

.

.

.

}

}

Factories

Factories are integral to the operation of JID, as they are needed for deserialization. (JID uses factory objects to create Jid objects, with each factory assigned a type name. See JActor Factories for more information.) Our main method begins with initializing the factories.

JAFactory factory = new JAFactory();

(new JidFactories()).initialize(factory);

JAFactory is the repository of factory objects. JidFactories, when initialized, adds a number of useful Jid factory objects to JAFactory when initialized.

Creating and Serializing an Empty RootJid

Jid objects are used to create tree structures, with the root of the tree always an instance of class RootJid.

The rootJid0 object is created and initialized by the JAFactory.newActor method.

The RootJid.getSerializedLength method returns the length of the byte array needed to hold the serialized RootJid. This method involves a minimum of calculation using information that is updated when the contents of the RootJid is updated. And the length is zero when a RootJid is empty.

The RootJid.save method takes two arguments, (1) the byte array where the serialized data is to be saved and (2) an offset. The returned value is the sum of the offset and the length of the serialized data.

The RootJid.load method is used to load a RootJid with the serialized data created by the method RootJid.save. The load method takes 3 arguments, (1) the byte array holding the serialized data, (2) the offset to where the serialized data is located in the byte array and (3) the length of the serialized data. The returned value is the sum of the offset and the length of the serialized data.

Serializing a RootJid with an Empty String

A RootJid object can hold one Jid object.

rootJid0.setValue(JidFactories.STRING_JID_TYPE);

serializedLength0 = rootJid0.getSerializedLength();

serializedData0 = new byte[serializedLength0];

updatedOffset0 = rootJid0.save(serializedData0, 0);

if (!(rootJid0.getValue() instanceof StringJid))

throw new Exception("unexpected result");

if (updatedOffset0 != serializedLength0)

throw new Exception("unexpected result");

The RootJid.setValue method is used to create and initialize the Jid object held by a RootJid.

Java Incremental Deserialization/reserialization (JID) provides a near-ideal solution for updating serialized data structures. On an Intel I7, an entry can be inserted in the middle of the byte array of a serialized list with 100,000 entries in 2.4 * 10^-4 seconds (240 microseconds or about a quarter of a millisecond). And an entry can be updated in the byte array of a serialized map with 100,000 entries in 4.8 * 10^-4 seconds (480 microseconds or about half a millisecond).

To achieve this level of performance, JID is not reflection based, nor does it support cyclic data structures. JID instead requires that serializable data structures be built with objects which are instances of the Jid class. Each type of object used in a serializable data structure must also be registered.