Difference between revisions of "EclipseLink/DesignDocs/406993"

From Eclipsepedia

Jump to: navigation, search
(New page: <div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div> = Design Specification: Serializers = [http://bugs.eclipse.org/406993 ER 406993] [[Talk:EclipseLink...)
 
Line 35: Line 35:
 
* API for custom or third party serializer
 
* API for custom or third party serializer
  
 +
Support using custom serializer for cache coordination.
  
 
= Design Constraints =
 
= Design Constraints =
 
+
Some serializers require additional configuration or code, the user is responsible for ensuring their objects can be serialized correctly with their serializer.
  
 
= Functionality =
 
= Functionality =
 +
* Support Serializer interface, JavaSerializer, XMLSerializer, JSONSerializer, KryoSerializer.
 +
* Serialization to both byte[] and String will be supported.
 +
* XML and JSON will use JAXB, JAXBContext can be specified, or package of first descriptor class will be used by default.
 +
* Cache coordination will send a byte[] instead of Command, which is the serialized Command, if no serializer is used, Command will still be sent as previous.
 +
* Cache coordination will use Session default serializer if set.
 +
* Cache coordination will not support XML or JSON (unless user maps change sets through JAXB), will be tested with Kryo.
 +
* SerializedObjectConverter will support serializers.
 +
* JPA annotations and XML will also config of serializer on SerializedObjectConverter, including specifying package for XML/JSON.
 +
* Serializer package will be defaulted to package of mapping's attribute type.
 +
* RemoteSession also has some support for serializers.
  
 +
= API =
 +
* Serializer
 +
* JavaSerializer
 +
* XMLSerializer
 +
* JSONSerializer
 +
* KryoSerializer
 +
* Session.setSerializer(Serializer)
 +
* @SerializedConverter(name, serializerClass, serializerPackage)
 +
* @Convert reserved names as statics, SERIALIZED, CLASS_INSTANCE, XML, JSON, KRYO
  
 
+
===Example===
= API =
+
<source lang="java">
 +
@SerializedConverter(name="binarySerializer", serializerClass=KryoSerializer.class)
 +
public class Employee {
 +
  ...
 +
  @Convert(Convert.XML)
 +
  private Resume resume;
 +
  @Convert(Convert.JSON)
 +
  private JobDetails jobDetails;
 +
  @Convert("binarySerializer")
 +
  private Image picture;
 +
}
 +
</source>
  
 
= Config files =
 
= Config files =
  
 
===persistence.xml===
 
===persistence.xml===
 +
* "eclipselink.cache.coordination.serializer"="<serializer-class>"
  
 
= Documentation =
 
= Documentation =
 +
Need to document serializers API, and new JPA annotations/xml.
 +
Need to document how to use custom serializer with cache coordination.
  
 
= Open Issues=
 
= Open Issues=

Revision as of 11:55, 1 May 2013

Design Specification: Serializers

ER 406993

Feedback

Document History

Date Author Version Description & Notes
2013-05-01 James 0.1 Draft

Project overview

This project will provide a pluggable Serializer interface and implementations to allow different serialization mechanisms to be used for any of EclipseLink's usages of serialization.

Concepts

Serialization means converting an object (or object graph) into a binary or character form.

Requirements

Support serializer interface and implementations for;

  • Java serialization
  • XML serialization through JAXB
  • JSON serialization through EclipseLink Moxy JAXB
  • Kryo serialization (for optimized binary serialization)
  • API for custom or third party serializer

Support using custom serializer for cache coordination.

Design Constraints

Some serializers require additional configuration or code, the user is responsible for ensuring their objects can be serialized correctly with their serializer.

Functionality

  • Support Serializer interface, JavaSerializer, XMLSerializer, JSONSerializer, KryoSerializer.
  • Serialization to both byte[] and String will be supported.
  • XML and JSON will use JAXB, JAXBContext can be specified, or package of first descriptor class will be used by default.
  • Cache coordination will send a byte[] instead of Command, which is the serialized Command, if no serializer is used, Command will still be sent as previous.
  • Cache coordination will use Session default serializer if set.
  • Cache coordination will not support XML or JSON (unless user maps change sets through JAXB), will be tested with Kryo.
  • SerializedObjectConverter will support serializers.
  • JPA annotations and XML will also config of serializer on SerializedObjectConverter, including specifying package for XML/JSON.
  • Serializer package will be defaulted to package of mapping's attribute type.
  • RemoteSession also has some support for serializers.

API

  • Serializer
  • JavaSerializer
  • XMLSerializer
  • JSONSerializer
  • KryoSerializer
  • Session.setSerializer(Serializer)
  • @SerializedConverter(name, serializerClass, serializerPackage)
  • @Convert reserved names as statics, SERIALIZED, CLASS_INSTANCE, XML, JSON, KRYO

Example

@SerializedConverter(name="binarySerializer", serializerClass=KryoSerializer.class)
public class Employee {
  ...
  @Convert(Convert.XML)
  private Resume resume;
  @Convert(Convert.JSON)
  private JobDetails jobDetails;
  @Convert("binarySerializer")
  private Image picture;
}

Config files

persistence.xml

  • "eclipselink.cache.coordination.serializer"="<serializer-class>"

Documentation

Need to document serializers API, and new JPA annotations/xml. Need to document how to use custom serializer with cache coordination.

Open Issues

Issue # Owner Description / Notes

Decisions

Issue # Description / Notes Decision

Future Considerations

  • Support additional serializers.