net.razorvine.pickle

Class Pickler

java.lang.Object

net.razorvine.pickle.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 and Description
protected static class	Pickler.Memo A memoized object.

Field Summary

Fields

Modifier and Type	Field and 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 and Description
Pickler() Create a Pickler.
Pickler(boolean useMemo) Create a Pickler.
Pickler(boolean useMemo, boolean valueCompare) Create a Pickler.

Method Summary

Modifier and Type	Method and 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.

customPicklers

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. You can add to this via registerCustomPickler(java.lang.Class<?>, net.razorvine.pickle.IObjectPickler)

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