carp_serializable 1.2.0

Polymorphic JSON serialization based on json_serializable annotations.

CARP Serialization

A package for polymorphic serialization to/from JSON build on top of json_serializable.

This package allows for implementing serialization and deserialization to/from JSON. This is done using the json_serializable package, so please study how the json_serializable package works, before using this package.

The key feature of this package is that it extends json_serializable with support for serialization of polymorphic classes, i.e. classes that inherits from each other. This is done by adding type information to the json.

Getting started

To use this package, add carp_serializable and json_annotation as dependencies in your pubspec.yaml file. Also add build_runner and json_serializable to the dev_dependencies:

dependencies:
  flutter:
    sdk: flutter
  json_annotation: ^latest
  carp_serializable: ^latest

dev_dependencies:
  flutter_test:
    sdk: flutter
  build_runner: any   # For building json serialization
  json_serializable: any

Usage

To support polymorphic serialization, each class should:

• extend from Serializable
• annotate the class with @JsonSerializable
• add the three json methods
  • Function get fromJsonFunction => ...
  • factory ...fromJson(...)
  • Map<String, dynamic> toJson() => ...
• register the classes in the FromJsonFactory() registry.
• build json function using the flutter pub run build_runner build --delete-conflicting-outputs command

Below is a simple example of two classes A and B where B extends A.

@JsonSerializable()
class A extends Serializable {
  int index;

  A() : super();

  Function get fromJsonFunction => _$AFromJson;
  factory A.fromJson(Map<String, dynamic> json) => FromJsonFactory().fromJson(json) as A;
  Map<String, dynamic> toJson() => _$AToJson(this);
}

@JsonSerializable()
class B extends A {
  String str;

  B() : super();

  Function get fromJsonFunction => _$BFromJson;
  factory B.fromJson(Map<String, dynamic> json) => FromJsonFactory().fromJson(json) as B;
  Map<String, dynamic> toJson() => _$BToJson(this);
}

Note that the naming of the fromJson() and toJson() functions follows the json_serializable package. For example the fromJson function for class A is called _$AFromJson.

The fromJsonFunction must be registered on app startup (before use of de-serialization) in the FromJsonFactory singleton, like this:

 FromJsonFactory().register(A());

For this purpose it is helpful to have an empty constructor, but any constructor will work, since only the fromJsonFunction function is used.

Polymorphic serialization is handled by setting the __type property in the Serializable class. Per default, an object's runtimeType is used as the __type for an object. Hence, the json of object of type A and B would look like this:

 {
  "__type": "A",
  "index": 1
 }
 {
  "__type": "B",
  "index": 2
  "str": "abc"
 }

However, if you want to specify your own class type (e.g., if you get json serialized from another language which uses a package structure like Java, C# or Kotlin), you can specify the json type in the jsonType property of the class.

For example, if the class B above should use a different __type annotation, using the following:

 @JsonSerializable()
 class B extends A {

   <<as above>>

   String get jsonType => 'dk.cachet.$runtimeType';
 }

In which case the json would look like:

 {
  "__type": "dk.cachet.B",
  "index": 2
  "str": "abc"
 }

Once the serialization code is used as above, run the

flutter pub run build_runner build --delete-conflicting-outputs

command as usual to generate the toJson() and fromJson() methods.

Features and bugs

Please read about existing issues and file new feature requests and bug reports at the issue tracker.

License

This software is copyright (c) Copenhagen Center for Health Technology (CACHET) at the Technical University of Denmark (DTU). This software is available 'as-is' under a MIT license.