Package net.razorvine.pickle

Class Pickler

  • public class Pickler
extends java.lang.Object
    Pickle an object graph into a Python-compatible pickle stream. For simplicity, the only supported pickle protocol at this time is protocol 2. This class is NOT threadsafe! (Don't use the same pickler from different threads) See the README.txt for a table with the type mappings.
    Author:
    Irmen de Jong (irmen@razorvine.net)

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected static class  Pickler.Memo
      A memoized object.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static java.util.Map<java.lang.Class<?>,​IObjectDeconstructor> customDeconstructors
      Registry of deconstructors for custom classes, to be able to pickle custom classes and also reconstruct.
      protected static java.util.Map<java.lang.Class<?>,​IObjectPickler> customPicklers
      Registry of picklers for custom classes, to be able to not just pickle simple built in datatypes.
      static int HIGHEST_PROTOCOL
      The highest Python pickle protocol supported by this Pickler.
      protected static int MAX_RECURSE_DEPTH
      Limit on the recursion depth to avoid stack overflows.
      protected java.util.HashMap<java.lang.Integer,​Pickler.Memo> memo
      The memoization cache.
      protected java.io.OutputStream out
      Output where the pickle data is written to.
      protected int PROTOCOL
      The Python pickle protocol version of the pickles created by this library.
      protected int recurse
      Current recursion level.
      protected boolean useMemo
      Use memoization or not.
      protected boolean valueCompare
      When memoizing, compare objects by value.

    • Constructor Summary

      Constructors 
      Constructor Description
      Pickler()
      Create a Pickler.
      Pickler​(boolean useMemo)
      Create a Pickler.
      Pickler​(boolean useMemo, boolean valueCompare)
      Create a Pickler.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Close the pickler stream, discard any internal buffers.
      void dump​(java.lang.Object o, java.io.OutputStream stream)
      Pickle a given object graph, writing the result to the output stream.
      byte[] dumps​(java.lang.Object o)
      Pickle a given object graph, returning the result as a byte array.
      protected IObjectDeconstructor getCustomDeconstructor​(java.lang.Class<?> t)
      Get the custom deconstructor fot the given class, to be able to pickle and unpickle custom classes A custom deconstructor is matched on the interface or abstract base class that the object implements or inherits from.
      protected IObjectPickler getCustomPickler​(java.lang.Class<?> t)
      Get the custom pickler fot the given class, to be able to pickle not just built in collection types.
      protected java.lang.Object persistentId​(java.lang.Object obj)
      Hook for the persistent id feature where an object is replaced externally by an id
      static void registerCustomDeconstructor​(java.lang.Class<?> clazz, IObjectDeconstructor deconstructor)
      Register custom object deconstructor for custom classes.
      static void registerCustomPickler​(java.lang.Class<?> clazz, IObjectPickler pickler)
      Register additional object picklers for custom classes.
      void save​(java.lang.Object o)
      Pickle a single object and write its pickle representation to the output stream.
      protected void writeMemo​(java.lang.Object obj)
      Write the object to the memo table and output a memo write opcode Only works for hashable objects

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Pickler

        public Pickler()
        Create a Pickler.

      • Pickler

        public Pickler​(boolean useMemo)
        Create a Pickler. Specify if it is to use a memo table or not. The memo table is NOT reused across different calls. If you use a memo table, you can only pickle objects that are hashable.

      • Pickler

        public Pickler​(boolean useMemo,
               boolean valueCompare)
        Create a Pickler. Also specify if it is to compare objects by value. If you compare objects by value, the object graph might be altered, as different instances with the same value will be unified. (The default for valueCompare when creating a pickler is true, so if this is problematic for you, you can turn it off here)

    • Method Detail

      • close

        public void close()
           throws java.io.IOException
        Close the pickler stream, discard any internal buffers.
        Throws:
        java.io.IOException

      • registerCustomPickler

        public static void registerCustomPickler​(java.lang.Class<?> clazz,
                                         IObjectPickler pickler)
        Register additional object picklers for custom classes. If you register an interface or abstract base class, it means the pickler is used for the whole inheritance tree of all classes ultimately implementing that interface or abstract base class. If you register a normal concrete class, the pickler is only used for objects of exactly that particular class.

      • registerCustomDeconstructor

        public static void registerCustomDeconstructor​(java.lang.Class<?> clazz,
                                               IObjectDeconstructor deconstructor)
        Register custom object deconstructor for custom classes. An alternative for writing your own pickler, you can create a deconstructor which will have a name & module, and the deconstructor will convert an object to a list of objects which will then be used as the arguments for reconstructing when unpickling.

      • dumps

        public byte[] dumps​(java.lang.Object o)
             throws PickleException,
                    java.io.IOException
        Pickle a given object graph, returning the result as a byte array.
        Throws:
        PickleException
        java.io.IOException

      • dump

        public void dump​(java.lang.Object o,
                 java.io.OutputStream stream)
          throws java.io.IOException,
                 PickleException
        Pickle a given object graph, writing the result to the output stream.
        Throws:
        java.io.IOException
        PickleException

      • save

        public void save​(java.lang.Object o)
          throws PickleException,
                 java.io.IOException
        Pickle a single object and write its pickle representation to the output stream. Normally this is used internally by the pickler, but you can also utilize it from within custom picklers. This is handy if as part of the custom pickler, you need to write a couple of normal objects such as strings or ints, that are already supported by the pickler. This method can be called recursively to output sub-objects.
        Throws:
        PickleException
        java.io.IOException

      • writeMemo

        protected void writeMemo​(java.lang.Object obj)
                  throws java.io.IOException
        Write the object to the memo table and output a memo write opcode Only works for hashable objects
        Throws:
        java.io.IOException

      • getCustomPickler

        protected IObjectPickler getCustomPickler​(java.lang.Class<?> t)
        Get the custom pickler fot the given class, to be able to pickle not just built in collection types. A custom pickler is matched on the interface or abstract base class that the object implements or inherits from.
        Parameters:
        t - the class of the object to be pickled
        Returns:
        null (if no custom pickler found) or a pickler registered for this class (via registerCustomPickler(java.lang.Class<?>, net.razorvine.pickle.IObjectPickler))

      • getCustomDeconstructor

        protected IObjectDeconstructor getCustomDeconstructor​(java.lang.Class<?> t)
        Get the custom deconstructor fot the given class, to be able to pickle and unpickle custom classes A custom deconstructor is matched on the interface or abstract base class that the object implements or inherits from.
        Parameters:
        t - the class of the object to be pickled
        Returns:
        null (if no custom deconstructor found) or a deconstructor registered for this class (via registerCustomDeconstructor(java.lang.Class<?>, net.razorvine.pickle.IObjectDeconstructor))

      • persistentId

        protected java.lang.Object persistentId​(java.lang.Object obj)
        Hook for the persistent id feature where an object is replaced externally by an id
        Parameters:
        obj - the object to replace with an id
        Returns:
        the id object that belongs to this object, or null if this object isn't replaced by an id.