jserialize               package:rJava               R Documentation

_J_a_v_a _o_b_j_e_c_t _s_e_r_i_a_l_i_z_a_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     '.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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

       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).

_D_e_t_a_i_l_s:

     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
     errorneous 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.

_V_a_l_u_e:

     '.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.

