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...)
 
(Functionality)
 
(One intermediate revision by one user not shown)
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 allow 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=

Latest revision as of 11:57, 1 May 2013

[edit] Design Specification: Serializers

ER 406993

Feedback

[edit] Document History

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

[edit] 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.

[edit] Concepts

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

[edit] 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.

[edit] Design Constraints

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

[edit] 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 allow 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.

[edit] API

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

[edit] 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;
}

[edit] Config files

[edit] persistence.xml

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

[edit] Documentation

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

[edit] Open Issues

Issue # Owner Description / Notes

[edit] Decisions

Issue # Description / Notes Decision

[edit] Future Considerations

  • Support additional serializers.