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<?>,​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 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.
      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

    • Field Detail

      • HIGHEST_PROTOCOL

        public static int HIGHEST_PROTOCOL
        The highest Python pickle protocol supported by this Pickler.

      • MAX_RECURSE_DEPTH

        protected static int MAX_RECURSE_DEPTH
        Limit on the recursion depth to avoid stack overflows.

      • recurse

        protected int recurse
        Current recursion level.

      • out

        protected java.io.OutputStream out
        Output where the pickle data is written to.

      • PROTOCOL

        protected int PROTOCOL
        The Python pickle protocol version of the pickles created by this library.

      • useMemo

        protected boolean useMemo
        Use memoization or not. This saves pickle size, but can only create pickles of objects that are hashable.

      • valueCompare

        protected boolean valueCompare
        When memoizing, compare objects by value. This saves pickle size, but can slow down pickling. Also, it should only be used if the object graph is immutable. Unused if useMemo is false.

      • memo

        protected java.util.HashMap<java.lang.Integer,​Pickler.Memo> memo
        The memoization cache.

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

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