<commit_before>Kryo JARs are in the [download section](https://code.google.com/p/kryo/downloads/list) and [Maven Central](http://search.maven.org/#browse|1975274176). Latest snapshots of Kryo including the builds of a current trunk are in the [Sonatype Repository](https://oss.sonatype.org/content/repositories/snapshots/com/esotericsoftware/kryo/kryo).

## New!

Kryo 2.22 was just released. This release fixes a lot of reported issues and aims for improved stability and performance. It also introduces many new features, most notably that it can use Unsafe to read and write object memory directly, which is the absolute fastest way to do serialization, especially for large primitive arrays. 

For those using the maven repo: the main jar now contains the required dependencies (like e.g. asm, with "relocated" class names) to avoid conflicts with a different version used by your application. There's no longer a separate shaded jar.

## Overview

Kryo is a fast and efficient object graph serialization framework for Java. The goals of the project are speed, efficiency, and an easy to use API. The project is useful any time objects need to be persisted, whether to a file, database, or over the network.

Kryo can also perform automatic deep and shallow copying/cloning. This is direct copying from object to object, not object->bytes->object.

This documentation is for v2 of Kryo. See [V1Documentation](https://github.com/EsotericSoftware/kryo/wiki/Documentation-for-Kryo-version-1.x) for v1.x.

If you are planning to use Kryo for network communication, the [KryoNet](http://code.google.com/p/kryonet/) project may prove useful.

## Contents

- [Quickstart](#quickstart)
- [IO](#io)
- [Unsafe-based IO](#unsafe-based-io)
- [Serializers](#serializers)
- [Registration](#registration)
- [Default serializers](#default-serializers)
- [FieldSerializer](#fieldserializer)
- [KryoSerializable](#kryoserializable)
- [Reading and writing](#reading-and-writing)
- [References](#references)
- [Object creation](#object-creation)
- [Copying/cloning](#copyingcloning)
- [Context](#context)
- [Compression and encryption](#compression-and-encryption)
- [Chunked encoding](#chunked-encoding)
- [Compatibility](#compatibility)
- [Interoperability](#interoperability)
- [Stack size](#stack-size)
- [Threading](#threading)
- [Logging](#logging)
- [Integration with Maven](#integration-with-maven)
- [Scala](#scala)
- [Objective-C](#objective-c)
- [Benchmarks](#benchmarks)
- [Projects using Kryo](#projects-using-kryo)
- [Contact / Mailing list](#contact--mailing-list)

## Quickstart

Jumping ahead to show how the library is used:

```java
    Kryo kryo = new Kryo();
    // ...
    Output output = new Output(new FileOutputStream("file.bin"));
    SomeClass someObject = ...
    kryo.writeObject(output, someObject);
    output.close();
    // ...
    Input input = new Input(new FileInputStream("file.bin"));
    SomeClass someObject = kryo.readObject(input, SomeClass.class);
    input.close();
```

The Kryo class orchestrates serialization. The Output and Input classes handle buffering bytes and optionally flushing to a stream.

The rest of this document details how this works and advanced usage of the library.

## IO

The Output class is an OutputStream that writes data to a byte array buffer. This buffer can be obtained and used directly, if a byte array is desired. If the Output is given an OutputStream, it will flush the bytes to the stream when the buffer becomes full. Output has many methods for efficiently writing primitives and strings to bytes. It provides functionality similar to DataOutputStream, BufferedOutputStream, FilterOutputStream, and ByteArrayOutputStream.

Because Output buffers when writing to an OutputStream, be sure to call `flush()` or `close()` after writing is complete so the buffered bytes are written to the underlying stream.

The Input class is an InputStream that reads data from a byte array buffer. This buffer can be set directly, if reading from a byte array is desired. If the Input is given an InputStream, it will fill the buffer from the stream when the buffer is exhausted. Input has many methods for efficiently reading primitives and strings from bytes. It provides functionality similar to DataInputStream, BufferedInputStream, FilterInputStream, and ByteArrayInputStream.

To read from a source or write to a target other than a byte array, simply provide the appropriate InputStream or OutputStream.

## Unsafe-based IO

Kryo provides additional IO classes, which are based on the functionalities exposed by the sun.misc.Unsafe class. These classes are UnsafeInput, UnsafeOutput. They are derived from Kryo's Input and Output classes and therefore can be used as a drop-in replacement on those platforms, which properly support sun.misc.Unsafe.

For the case you need to serialize to or deserialize from direct-memory ByteBuffers or even off-heap memory, there are two dedicated classes UnsafeMemoryInput and UnsafeMemoryOutput whose instances can be used for this purpose instead of the usual Input and Output classes.

Using Unsafe-based IO may result in a quite significant performance boost, depending on your application. In particular, it helps a lot when serializing large primitive arrays as part of your object graphs.

### ** DISCLAIMER ABOUT USING UNSAFE-BASED IO **

*Unsafe-based IO is not 100% compatible with Kryo's Input and Output streams when it comes to the binary  format of serialized data!* 

This means that data written by Unsafe-based output streams can be read only by  
Unsafe-based input streams, but not by usual Input streams. The same applies on the opposite direction: data written by usual Output streams cannot be correctly read by Unsafe-based input streams.

It should be safe to use Unsafe IO streams as long as both serialization and deserialization are using them and are executed on the same processor architecture (more precisely, if the endianness and internal representation of native integer and floating point types is the same).

## Serializers

Kryo is a serialization framework. It doesn't enforce a schema or care what data is written or read. This is left to the serializers themselves. Serializers are provided by default to read and write data in various ways. If these don't meet particular needs, they can be replaced in part or in whole. The provided serializers can read and write most objects but, if necessary, writing a new serializer is easy. The Serializer abstract class defines methods to go from objects to bytes and bytes to objects.

    public class ColorSerializer extends Serializer<Color> {
    	public void write (Kryo kryo, Output output, Color object) {
    		output.writeInt(object.getRGB());
    	}
    
    	public Color read (Kryo kryo, Input input, Class<T> type) {
    		return new Color(input.readInt(), true);
    	}
    }

Serializer has two methods that can be implemented. `write()` writes the object as bytes. `read()` creates a new instance of the object and reads from the input to populate it.

The Kryo instance can be used to write and read nested objects. If Kryo is used to read a nested object in `read()` then `kryo.reference()` must first be called with the parent object if it is possible for the nested object to reference the parent object. It is unnecessary to call `kryo.reference()` if the nested objects can't possibly reference the parent object, Kryo is not being used for nested objects, or references are not being used. If nested objects can use the same serializer, the serializer must be reentrant.

Code should not make use of serializers directly, instead the Kryo read and write methods should be used. This allows Kryo to orchestrate serialization and handle features such as references and null objects.

By default, serializers do not need to handle the object being null. The Kryo framework will write a byte as needed denoting null or not null. If a serializer wants to be more efficient and handle nulls itself, it can call `Serializer#setAcceptsNull(true)`. This can also be used to avoid writing the null denoting byte when it is known that all instances of a type will never be null.

## Registration

When Kryo writes out an instance of an object, first it may need to write out something that identifies the object's class. By default, the fully qualified class name is written, then the bytes for the object. Subsequent appearances of that object type within the same object graph are written using a variable length int. Writing the class name is somewhat inefficient, so classes can be registered beforehand:

```java
    Kryo kryo = new Kryo();
    kryo.register(SomeClass.class);<commit_msg>add missing block<commit_after>Kryo JARs are in the [download section](https://code.google.com/p/kryo/downloads/list) and [Maven Central](http://search.maven.org/#browse|1975274176). Latest snapshots of Kryo including the builds of a current trunk are in the [Sonatype Repository](https://oss.sonatype.org/content/repositories/snapshots/com/esotericsoftware/kryo/kryo).

## New!

Kryo 2.22 was just released. This release fixes a lot of reported issues and aims for improved stability and performance. It also introduces many new features, most notably that it can use Unsafe to read and write object memory directly, which is the absolute fastest way to do serialization, especially for large primitive arrays. 

For those using the maven repo: the main jar now contains the required dependencies (like e.g. asm, with "relocated" class names) to avoid conflicts with a different version used by your application. There's no longer a separate shaded jar.

## Overview

Kryo is a fast and efficient object graph serialization framework for Java. The goals of the project are speed, efficiency, and an easy to use API. The project is useful any time objects need to be persisted, whether to a file, database, or over the network.

Kryo can also perform automatic deep and shallow copying/cloning. This is direct copying from object to object, not object->bytes->object.

This documentation is for v2 of Kryo. See [V1Documentation](https://github.com/EsotericSoftware/kryo/wiki/Documentation-for-Kryo-version-1.x) for v1.x.

If you are planning to use Kryo for network communication, the [KryoNet](http://code.google.com/p/kryonet/) project may prove useful.

## Contents

- [Quickstart](#quickstart)
- [IO](#io)
- [Unsafe-based IO](#unsafe-based-io)
- [Serializers](#serializers)
- [Registration](#registration)
- [Default serializers](#default-serializers)
- [FieldSerializer](#fieldserializer)
- [KryoSerializable](#kryoserializable)
- [Reading and writing](#reading-and-writing)
- [References](#references)
- [Object creation](#object-creation)
- [Copying/cloning](#copyingcloning)
- [Context](#context)
- [Compression and encryption](#compression-and-encryption)
- [Chunked encoding](#chunked-encoding)
- [Compatibility](#compatibility)
- [Interoperability](#interoperability)
- [Stack size](#stack-size)
- [Threading](#threading)
- [Logging](#logging)
- [Integration with Maven](#integration-with-maven)
- [Scala](#scala)
- [Objective-C](#objective-c)
- [Benchmarks](#benchmarks)
- [Projects using Kryo](#projects-using-kryo)
- [Contact / Mailing list](#contact--mailing-list)

## Quickstart

Jumping ahead to show how the library is used:

```java
    Kryo kryo = new Kryo();
    // ...
    Output output = new Output(new FileOutputStream("file.bin"));
    SomeClass someObject = ...
    kryo.writeObject(output, someObject);
    output.close();
    // ...
    Input input = new Input(new FileInputStream("file.bin"));
    SomeClass someObject = kryo.readObject(input, SomeClass.class);
    input.close();
```

The Kryo class orchestrates serialization. The Output and Input classes handle buffering bytes and optionally flushing to a stream.

The rest of this document details how this works and advanced usage of the library.

## IO

The Output class is an OutputStream that writes data to a byte array buffer. This buffer can be obtained and used directly, if a byte array is desired. If the Output is given an OutputStream, it will flush the bytes to the stream when the buffer becomes full. Output has many methods for efficiently writing primitives and strings to bytes. It provides functionality similar to DataOutputStream, BufferedOutputStream, FilterOutputStream, and ByteArrayOutputStream.

Because Output buffers when writing to an OutputStream, be sure to call `flush()` or `close()` after writing is complete so the buffered bytes are written to the underlying stream.

The Input class is an InputStream that reads data from a byte array buffer. This buffer can be set directly, if reading from a byte array is desired. If the Input is given an InputStream, it will fill the buffer from the stream when the buffer is exhausted. Input has many methods for efficiently reading primitives and strings from bytes. It provides functionality similar to DataInputStream, BufferedInputStream, FilterInputStream, and ByteArrayInputStream.

To read from a source or write to a target other than a byte array, simply provide the appropriate InputStream or OutputStream.

## Unsafe-based IO

Kryo provides additional IO classes, which are based on the functionalities exposed by the sun.misc.Unsafe class. These classes are UnsafeInput, UnsafeOutput. They are derived from Kryo's Input and Output classes and therefore can be used as a drop-in replacement on those platforms, which properly support sun.misc.Unsafe.

For the case you need to serialize to or deserialize from direct-memory ByteBuffers or even off-heap memory, there are two dedicated classes UnsafeMemoryInput and UnsafeMemoryOutput whose instances can be used for this purpose instead of the usual Input and Output classes.

Using Unsafe-based IO may result in a quite significant performance boost, depending on your application. In particular, it helps a lot when serializing large primitive arrays as part of your object graphs.

### ** DISCLAIMER ABOUT USING UNSAFE-BASED IO **

*Unsafe-based IO is not 100% compatible with Kryo's Input and Output streams when it comes to the binary  format of serialized data!* 

This means that data written by Unsafe-based output streams can be read only by  
Unsafe-based input streams, but not by usual Input streams. The same applies on the opposite direction: data written by usual Output streams cannot be correctly read by Unsafe-based input streams.

It should be safe to use Unsafe IO streams as long as both serialization and deserialization are using them and are executed on the same processor architecture (more precisely, if the endianness and internal representation of native integer and floating point types is the same).

## Serializers

Kryo is a serialization framework. It doesn't enforce a schema or care what data is written or read. This is left to the serializers themselves. Serializers are provided by default to read and write data in various ways. If these don't meet particular needs, they can be replaced in part or in whole. The provided serializers can read and write most objects but, if necessary, writing a new serializer is easy. The Serializer abstract class defines methods to go from objects to bytes and bytes to objects.

```java
    public class ColorSerializer extends Serializer<Color> {
    	public void write (Kryo kryo, Output output, Color object) {
    		output.writeInt(object.getRGB());
    	}
    
    	public Color read (Kryo kryo, Input input, Class<T> type) {
    		return new Color(input.readInt(), true);
    	}
    }
```

Serializer has two methods that can be implemented. `write()` writes the object as bytes. `read()` creates a new instance of the object and reads from the input to populate it.

The Kryo instance can be used to write and read nested objects. If Kryo is used to read a nested object in `read()` then `kryo.reference()` must first be called with the parent object if it is possible for the nested object to reference the parent object. It is unnecessary to call `kryo.reference()` if the nested objects can't possibly reference the parent object, Kryo is not being used for nested objects, or references are not being used. If nested objects can use the same serializer, the serializer must be reentrant.

Code should not make use of serializers directly, instead the Kryo read and write methods should be used. This allows Kryo to orchestrate serialization and handle features such as references and null objects.

By default, serializers do not need to handle the object being null. The Kryo framework will write a byte as needed denoting null or not null. If a serializer wants to be more efficient and handle nulls itself, it can call `Serializer#setAcceptsNull(true)`. This can also be used to avoid writing the null denoting byte when it is known that all instances of a type will never be null.

## Registration

When Kryo writes out an instance of an object, first it may need to write out something that identifies the object's class. By default, the fully qualified class name is written, then the bytes for the object. Subsequent appearances of that object type within the same object graph are written using a variable length int. Writing the class name is somewhat inefficient, so classes can be registered beforehand:

```java
    Kryo kryo = new Kryo();
    kryo.register(SomeClass.class);
{'fraction_non_alphanumeric': 0.0654926335174954, 'fraction_numerical': 0.0023020257826887663, 'mean_word_length': 4.574911774141803, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 11, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6825514', 'n_tokens_mistral': 4518, 'n_tokens_neox': 4312, 'n_words': 2332}