jserialize {rJava}

Java object serialization

Description

.jserialize serializes a Java object into raw vector using Java serialization.

.junserialize re-constructs a Java object from its serialized (raw-vector) form.

.jcache updates, retrieves or removes R-side object cache which can be used for persistent storage of Java objects across sessions.

Usage

.jserialize(o)
.junserialize(data)
.jcache(o, update=TRUE)

Arguments

o

Java object

data

serialized Java object as a raw vector

update

must be TRUE (cache is updated), FALSE (cache is retrieved) or NULL (cache is deleted).

Details

Not all Java objects support serialization, see Java documentation for details. Note that Java serialization and serialization of R objects are two entirely different mechanisms that cannot be interchanged. .jserialize and .junserialize can be used to access Java serialization facilities.

.jcache manipulates the R-side Java object cache associated with a given Java reference:

Java objects do not persist across sessions, because the Java Virtual Machine (JVM) is destroyed when R is closed. All saved Java object references will be restored as null references, since the corresponding objects no longer exist (see R documentation on serialization). However, it is possible to serialize a Java object (if supported by the object) and store its serialized form in R. This allows for the object to be deserialized when loaded into another active session (but see notes below!)

R-side cache consists of a serialized form of the object as raw vector. This cache is attached to the Java object and thus will be saved when the Java object is saved. rJava provides an automated way of deserializing Java references if they are null references and have a cache attached. This is done on-demand basis whenever a reference to a Java object is required.

Therefore packages can use .jcache to provide a way of creating Java references that persist across sessions. However, they must be very cautious in doing so. First, make sure the serialized form is not too big. Storing whole datasets in Java serialized form will hog immense amounts of memory on the R side and should be avoided. In addition, be aware that the cache is just a snapshot, it doesn't change when the referenced Java object is modified. Hence it is most useful only for references that are not modified outside R. Finally, internal references to other Java objects accessible from R are not retained (see below). Most common use of .jcache is with Java references that point to definitions of methods (e.g., models) and other descriptive objects which are then used by other, active Java classes to act upon. Caching of such active objects is not a good idea, they should be instantiated by functions that operate on the descriptive references instead.

Important note: the serialization of Java references does NOT take into account any dependencies on the R side. Therefore if you hold a reference to a Java object in R that is also referenced by the serialized Java object on the Java side, then this relationship cannot be retained upon restore. Instead, two copies of disjoint objects will be created which can cause confusion and erroneous behavior.

The cache is attached to the reference external pointer and thus it is shared with all copies of the same reference (even when changed via .jcast etc.), but it is independent of other references to the object obtained separately (e.g., via .jcall or .jfield).

Also note that deserialization (even automated one) requires a running virtual machine. Therefore you must make sure that either .jinit or .jpackage is used before any Java references are accessed.

Value

.jserialize returns a raw vector

.junserialize returns a Java object or NULL if an error occurred (currently you may use .jcheck() to further investigate the error)

.jcache returns the current cache (usually a raw vector) or NULL if there is no cache.