diff --git a/spring-geode-docs/src/docs/asciidoc/data-serialization.adoc b/spring-geode-docs/src/docs/asciidoc/data-serialization.adoc index 15d86e05..b779d944 100644 --- a/spring-geode-docs/src/docs/asciidoc/data-serialization.adoc +++ b/spring-geode-docs/src/docs/asciidoc/data-serialization.adoc @@ -17,7 +17,7 @@ for which you may have no control over. Furthermore, Java serialization is not the most efficient format given that meta-data about your types is stored with the data itself. Therefore, even though Java serialized bytes are more descriptive, it adds a great deal of overhead. -Then came Apache Geode & Pivotal GemFire's {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX serialization] +Then, along came serialization using Apache Geode or Pivotal GemFire's {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX] format. PDX stands for _Portable Data Exchange_, and achieves 4 goals: 1. Separates type meta-data from the data itself making the bytes more efficient during transfer. Apache Geode @@ -31,28 +31,29 @@ clients without loss of data. 3. Enables objects stored as PDX bytes to be queried without being de-serialized. Constant de/serialization of data is a resource intensive task adding to the latency of each data request when redundancy is enabled. Since data must be replicated across peers in the cluster to preserve High Availability (HA), and serialized to be transferred, keeping -data serialized is more efficient when data is updated since it will likely need to be transferred in order to maintain -redundancy and availability. +data serialized is more efficient when data is updated frequently since it will likely need to be transferred again +in order to maintain consistency in the face of redundancy and availability. 4. Enables interoperability between native language clients (e.g. C/C++/C#) and Java language clients, with each being able to access the same data set regardless from where the data originated. However, PDX is not without its limitations either. -For instance, unlike Java serialization, it does not handle cyclic dependencies. Therefore, you must be careful +For instance, unlike Java serialization, PDX does not handle cyclic dependencies. Therefore, you must be careful how you structure and design your application domain object types. -Also, PDX cannot handle field type changes. While GemFire/Geode's general -{apache-geode-docs}/developing/data_serialization/gemfire_data_serialization.html[Data Serialization] handles -{apache-geode-docs}/developing/delta_propagation/chapter_overview.html[deltas], this is not achievable without -de-serializing the object bytes since it involves a method invocation, which defeats 1 of the key benefits of PDX, -preserving format. +Also, PDX cannot handle field type changes. -However, we thing the benefits of using PDX greatly outweight the limitations and therefore have enabled PDX by default +Furthermore, while GemFire/Geode's general {apache-geode-docs}/developing/data_serialization/gemfire_data_serialization.html[Data Serialization] +handles {apache-geode-docs}/developing/delta_propagation/chapter_overview.html[deltas], this is not achievable without +de-serializing the object bytes since it involves a method invocation, which defeats 1 of the key benefits of PDX, +preserving format to avoid the cost of de/serialization. + +However, we think the benefits of using PDX greatly outweigh the limitations and therefore have enabled PDX by default when using Spring Boot for Apache Geode/Pivotal GemFire. There is nothing special you need to do. Simply code your types and rest assured that objects of those types will be -properly serialized when overflowed/persisted to disk, transferred between client and servers, or peers in the cluster +properly serialized when overflowed/persisted to disk, transferred between clients and servers, or peers in a cluster and even when data is transferred over the WAN when using GemFire/Geode's multi-site topology. .EligibilityDecision is automatically serialiable without implementing Java Serializable. @@ -69,7 +70,7 @@ the standard Java Serialization format. === SDG `MappingPdxSerializer` vs. GemFire/Geode's `ReflectionBasedAutoSerializer` -Under-the-hood, Spring Boot for Apache Geode/Pivotal GemFire {spring-data-geode-docs-html?/#bootstrap-annotation-config-pdx[enables] +Under-the-hood, Spring Boot for Apache Geode/Pivotal GemFire {spring-data-geode-docs-html}/#bootstrap-annotation-config-pdx[enables] and uses Spring Data for Apache Geode/Pivotal GemFire's {spring-data-geode-javadoc}/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[MappingPdxSerializer] to serialize your application domain objects using PDX. @@ -94,19 +95,19 @@ excludes all types in the following packages: `java`, `org.apache.geode`, `org.s 3. Handles {spring-data-geode-docs-html}/#mapping.pdx-serializer.transient-properties[transient object fields & properties] when either Java's `transient` keyword or Spring Data's `@Transient` annotation is used. -4. Handles {spring-data-geode-html}/#mapping.pdx-serializer.read-only-properties[read-only object properties]. +4. Handles {spring-data-geode-docs-html}/#mapping.pdx-serializer.read-only-properties[read-only object properties]. -5. Determines the identifier of your entities when you annotate the appropriate entity field or property with -Spring Data's {spring-data-commons-javadoc}/org/springframework/data/annotation/Id.html[@Id] annotation. +5. Automatically determines the identifier of your entities when you annotate the appropriate entity field or property +with Spring Data's {spring-data-commons-javadoc}/org/springframework/data/annotation/Id.html[@Id] annotation. -6. Allows `o.a.g.pdx.PdxSerializers` to be registered in order to {spring-data-geode-docs}/#mapping.pdx-serializer.custom-serialization[customize the serialization] +6. Allows `o.a.g.pdx.PdxSerializers` to be registered in order to {spring-data-geode-docs-html}/#mapping.pdx-serializer.custom-serialization[customize the serialization] of nested entity field/property types. Number two above deserves special attention since the `MappingPdxSerializer` "excludes" all Java, Spring and Apache Geode/Pivotal GemFire types, by default. But, what happens when you need to serialize 1 of those types? For example, suppose you need to be able to serialize objects of type `java.security.Principal`. Well, then you can -override the excludes by registering a "include" type filter, like so: +override the excludes by registering an "include" type filter, like so: [source,java] ----