• This repository has been archived on 20/Feb/2019
  • Stars
    star
    833
  • Rank 54,737 (Top 2 %)
  • Language
    Scala
  • License
    BSD 3-Clause "New...
  • Created over 11 years ago
  • Updated over 7 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Fast, customizable, boilerplate-free pickling support for Scala

scala/pickling

Build Status Stories in Ready Join the chat at https://gitter.im/scala/pickling

Scala Pickling is an automatic serialization framework made for Scala. It's fast, boilerplate-free, and allows users to easily swap in/out different serialization formats (such as binary, or JSON), or even to provide their own custom serialization format.

Defaults mode

scala> import scala.pickling.Defaults._, scala.pickling.json._
scala> case class Person(name: String, age: Int)

scala> val pkl = Person("foo", 20).pickle
pkl: pickling.json.pickleFormat.PickleType =
JSONPickle({
  "$type": "Person",
  "name": "foo",
  "age": 20
})

scala> val person = pkl.unpickle[Person]
person: Person = Person(foo,20)

For more, flip through, or watch the ScalaDays 2013 presentation!
For deeper technical details, we've also written an OOPSLA 2013 paper on scala/pickling, Instant Pickles: Generating Object-Oriented Pickler Combinators for Fast and Extensible Serialization.

Get Scala Pickling

Scala Pickling is available on Sonatype for Scala 2.10 and Scala 2.11! You can use Scala Pickling in your sbt project by simply adding the following dependency to your build file:

libraryDependencies += "org.scala-lang.modules" %% "scala-pickling" % "0.10.1"

Please, don't use the version 0.11.0-M1 since it's not production ready and it's still under ongoing development.

What makes it different?

Scala Pickling...

  • can be Language-Neutral if you want it to be. Changing the format of your serialized data is as easy as importing the correct implicit pickle format into scope. Out of the box, we currently support a fast Scala binary format, as well as JSON. Support is currently planned for other formats. Or, you can even roll your own custom pickle format!
  • is Automatic. That is, without any boilerplate at all, one can instruct the framework to figure out how to serialize an arbitrary class instance. No need to register classes, no need to implement any methods.
  • Allows For Unanticipated Evolution. That means that you donโ€™t have to extend some marker trait in order to serialize a given Scala class. Just import the scala.pickling package and call pickle on the instance that you would like to serialize.
  • gives you more Typesafety. No more errors from serialization/deserialization propagating to arbitrary points in your program. Unlike Java Serialization, errors either manifest themselves as compile-time errors, or runtime errors only at the point of unpickling.
  • has Robust Support For Object-Orientation. While Scala Pickling is based on the elegant notion of pickler combinators from functional programming, it goes on to extend the traditional form of pickler combinators to be able to handle open class hierarchies. That means that if you pickle an instance of a subclass, and then try to unpickle as a superclass, you will still get back an instance of the original subclass.
  • Happens At Compile-Time. That means that itโ€™s super-performant because serialization-related code is typically generated at compile-time and inlined where it is needed in your code. Scala Pickling is essentially fully-static, reflection is only used as a fallback when static (compile-time) generation fails.

Optimizing performance

Pickling enables optimizing performance through configuration, in case the pickled objects are known to be simpler than in the general case.

Disabling cyclic object graphs

By default, Pickling can serialize cyclic object graphs (for example, for serializing doubly-linked lists). However, this requires bookkeeping at run time. If pickled objects are known to be not cyclic (for example, simple lists or trees), then this additional bookkeeping can be disabled using the following import:

import scala.pickling.shareNothing._

If objects are pickled in a tight loop, this import can lead to a significant performance improvement.

Static serialization without reflection

To pickle objects of types like Any Pickling uses run-time reflection, since not enough information is available at compile time. However, Pickling supports a static-only mode that ensures no run-time reflection is used. In this mode, pickling objects that would otherwise require run-time reflection causes compile-time errors.

The following import enables static-only serialization:

import scala.pickling.static._  // Avoid run-time reflection

A la carte import

If you want, Pickling lets you import specific parts (functions, ops, picklers, and format) so you can customize each part.

import scala.pickling._         // This imports names only
import scala.pickling.json._    // Imports PickleFormat
import scala.pickling.static._  // Avoid runtime pickler

// Import pickle ops
import scala.pickling.Defaults.{ pickleOps, unpickleOps } 
// Alternatively import pickle function
// import scala.pickling.functions._

// Import picklers for specific types
import scala.pickling.Defaults.{ stringPickler, intPickler, refPicklerUnpickler, nullPickler }

case class Pumpkin(kind: String)
// Manually generate a pickler using macro
implicit val pumpkinPickler = Pickler.generate[Pumpkin]
implicit val pumpkinUnpickler = Unpickler.generate[Pumpkin]

val pckl = Pumpkin("Kabocha").pickle
val pump = pckl.unpickle[Pumpkin]

DIY protocol stack

There are also traits available for picklers to mix and match your own convenience object to import from. If you're a library author, you can provide the convenience object as your protocol stack that some or all of the pickling parts:

  • ops
  • functions
  • picklers
  • format
scala> case class Apple(kind: String)
defined class Apple

scala> val appleProtocol = {
     |              import scala.pickling._
     |              new pickler.PrimitivePicklers with pickler.RefPicklers
     |                  with json.JsonFormats {
     |                // Manually generate pickler for Apple
     |                implicit val applePickler = PicklerUnpickler.generate[Apple]
     |                // Don't fall back to runtime picklers
     |                implicit val so = static.StaticOnly
     |                // Provide custom functions
     |                def toJsonString[A: Pickler](a: A): String =
     |                  functions.pickle(a).value
     |                def fromJsonString[A: Unpickler](s: String): A =
     |                  functions.unpickle[A](json.JSONPickle(s))
     |              }
     |            }
appleProtocol: scala.pickling.pickler.PrimitivePicklers with scala.pickling.pickler.RefPicklers with scala.pickling.json.JsonFormats{implicit val applePickler: scala.pickling.Pickler[Apple] with scala.pickling.Unpickler[Apple] with scala.pickling.Generated; implicit val so: scala.pickling.static.StaticOnly.type; def toJsonString[A](a: A)(implicit evidence$1: scala.pickling.Pickler[A]): String; def fromJsonString[A](s: String)(implicit evidence$2: scala.pickling.Unpickler[A]): A} = $anon$1@2b033c35

Now your library user can import appleProtocol as follows:

scala> import appleProtocol._
import appleProtocol._

scala>  toJsonString(Apple("honeycrisp"))
res0: String =
{
  "$type": "Apple",
  "kind": "honeycrisp"
}

scala> fromJsonString(res0)
res1: Apple = Apple(honeycrisp)

Other ways of getting Pickling

If you would like to run the latest development version of scala/pickling (0.10.2-SNAPSHOT), you also need to add the Sonatype "snapshots" repository resolver to your build file:

libraryDependencies += "org.scala-lang.modules" %% "scala-pickling" % "0.10.2-SNAPSHOT"

resolvers += Resolver.sonatypeRepo("snapshots")

For a more illustrative example, see a sample sbt project which uses Scala Pickling.

Or you can just directly download the 0.10.1 jar (Scala 2.10, Scala 2.11).

More Repositories

1

scala

Scala 2 compiler and standard library. Bugs at https://github.com/scala/bug; Scala 3 at https://github.com/scala/scala3
Scala
14,269
star
2

scala3

The Scala 3 compiler, also known as Dotty.
Scala
5,786
star
3

scala-async

An asynchronous programming facility for Scala
Scala
1,138
star
4

scala-parser-combinators

simple combinator-based parsing for Scala. formerly part of the Scala standard library, now a separate community-maintained module
Scala
642
star
5

docs.scala-lang

The Scala Documentation website
HTML
559
star
6

scala-java8-compat

A Java 8 (and up) compatibility kit for Scala.
Scala
436
star
7

legacy-svn-scala

OBSOLETE, we're over there:
Scala
366
star
8

scala3-example-project

An example sbt project that compiles using Dotty
Scala
332
star
9

scala-xml

The standard Scala XML library
Scala
295
star
10

scala-dist

sbt project that packages the Scala distribution
Scala
276
star
11

scala-lang

sources for the Scala language website
SCSS
268
star
12

scala-abide

obsolete; visit https://github.com/scalacenter/scalafix instead
Scala
232
star
13

bug

Scala 2 bug reports only. Please, no questions โ€” proper bug reports only.
230
star
14

collection-strawman

Implementation of the new Scala 2.13 Collections
Scala
201
star
15

scala-collection-compat

makes some Scala 2.13 APIs (primarily collections, also some others) available on 2.11 and 2.12, to aid cross-building
Scala
200
star
16

scala-parallel-collections

Parallel collections standard library module for Scala 2.13+
Scala
194
star
17

scala-seed.g8

Giter8 template for a simple hello world app in Scala.
Scala
150
star
18

scala-dev

Scala 2 team issues. Not for user-facing bugs or directly actionable user-facing improvements. For build/test/infra and for longer-term planning and idea tracking. Our bug tracker is at https://github.com/scala/bug/issues
132
star
19

community-build

Scala 2 community build โ€”ย a corpus of open-source repos built against Scala nightlies
Shell
129
star
20

scala-swing

Scala wrappers for Java's Swing API for desktop GUIs
Scala
126
star
21

scala3.g8

Scala
123
star
22

scala-collection-contrib

community-contributed additions to the Scala 2.13 collections
Scala
107
star
23

scala-module-dependency-sample

Depend on Scala modules like a pro
Scala
95
star
24

scala-continuations

the Scala delimited continuations plugin and library
Scala
89
star
25

toolkit

The batteries-included Scala
Scala
87
star
26

make-release-notes

The project that generates Scala release notes.
HTML
85
star
27

vscode-scala-syntax

Visual Studio Code extension for syntax highlighting Scala sources
Scala
72
star
28

slip

obsolete โ€”ย archival use only
68
star
29

compiler-benchmark

Benchmarks for scalac
Scala
68
star
30

scala-library-next

backwards-binary-compatible Scala standard library additions
Scala
66
star
31

improvement-proposals

Scala Improvement Proposals
42
star
32

scala.epfl.ch

web site for the Scala Center @ EPFL in Switzerland
SCSS
37
star
33

scala-tool-support

XML
34
star
34

hello-world.g8

Scala
27
star
35

scala-collection-laws

partially-automatic generation of tests for the entire collections library
Scala
21
star
36

scala3-cross.g8

Scala
17
star
37

scabot

Scala's PR&CI automation bot
Scala
14
star
38

sbt-scala-module

sbt plugin for scala modules.
Scala
14
star
39

scala-jenkins-infra

A Chef cookbook that manages Scala's CI infrastructure.
Shell
14
star
40

scalatest-example.g8

Scala
13
star
41

scala3-mill-example-project

Shell
12
star
42

scala-asm

A fork of https://gitlab.ow2.org/asm/asm for the Scala compiler
12
star
43

compiler-interface

a binary contract between Zinc and Scala Compilers
Scala
10
star
44

scala-partest

Legacy repo for testing framework for Scala versions <= 2.12
Scala
9
star
45

scala-asm-legacy

A fork of asm.ow2.org for the Scala compiler
Java
8
star
46

scala3-staging.g8

Scala
7
star
47

scala-modules-build

Build support for the various Scala Modules
Shell
1
star
48

dotty.epfl.ch

The nightly documentation of scala 3
HTML
1
star
49

actors-migration

Scala
1
star
50

scala-partest-interface

SBT interface to partest
1
star
51

scala-library-all

Conglomerate pom file to pull in components of Scala standard library easily.
Scala
1
star
52

scala-dist-smoketest

Smoke Test for newly created Scala distributions
Shell
1
star
53

scala3-tasty-inspector.g8

Scala
1
star