SGF-776 - Edit MappingPdxSerializer type filter documentation to cover includes and excludes.

src/main/asciidoc/reference/mapping.adoc

@@ -5,7 +5,7 @@ This section covers:
 
 * <<mapping.entities>>
 * <<mapping.repositories>>
-* The <<Mapping PDX Serializer>>
+* <<Mapping PDX Serializer>>
 
 [[mapping.entities]]
 == Entity Mapping
@@ -125,18 +125,18 @@ You can even wrap the `update` service method in a Spring managed transaction, e
 or a global transaction.
 
 [[mapping.pdx-serializer]]
-== Mapping PDX Serializer
+== MappingPdxSerializer
 
 {sdg-name} provides a custom {x-data-store-javadoc}/org/apache/geode/pdx/PdxSerializer.html[`PdxSerializer`]
-implementation that uses the mapping information to customize entity serialization.
+implementation, called `MappingPdxSerializer`, that uses Spring Data mapping metadata to customize entity serialization.
 
-It also lets you customize entity instantiation by using the Spring Data `EntityInstantiator` abstraction.
+The serializer also lets you customize entity instantiation by using the Spring Data `EntityInstantiator` abstraction.
-By default, the serializer uses a `ReflectionEntityInstantiator` that uses the persistence constructor of
+By default, the serializer use the `ReflectionEntityInstantiator`, which uses the persistence constructor of
-the mapped entity (the default constructor, a singly declared constructor, or a constructor explicitly
+the mapped entity.  The persistence constructor is either the default constructor, a singly declared constructor,
-annotated with `@PersistenceConstructor`).
+or a constructor explicitly annotated with `@PersistenceConstructor`.
 
 To provide arguments for constructor parameters, the serializer reads fields with the named constructor parameter,
-explicitly specified using Spring's `@Value` annotation, from the supplied
+explicitly identified by using Spring's `@Value` annotation, from the supplied
 {x-data-store-javadoc}/org/apache/geode/pdx/PdxReader.html[`PdxReader`],
 as shown in the following example:
 
@@ -147,43 +147,43 @@ as shown in the following example:
 public class Person {
 
   public Person(@Value("#root.thing") String firstName, @Value("bean") String lastName) {
-    // …
+    …
   }
 }
 ----
 ====
 
-An entity class annotated in this way has the `thing` field read from the `PdxReader` and passed as the value
+An entity class annotated in this way has the "`thing`" field read from the `PdxReader` and passed as the argument value
 for the constructor parameter, `firstname`. The value for `lastName` is a Spring bean with the name "`bean`".
 
 In addition to the custom instantiation logic and strategy provided by `EntityInstantiators`,
 the `MappingPdxSerializer` also provides capabilities well beyond {data-store-name}'s own
 {x-data-store-javadoc}/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`].
 
-While {data-store-name}'s `ReflectionBasedAutoSerializer` conveniently uses Java reflection to populate entities
+While {data-store-name}'s `ReflectionBasedAutoSerializer` conveniently uses Java Reflection to populate entities
-and uses regular expressions to identify types that should be handled (serialized and deserialized) by
+and uses regular expressions to identify types that should be handled (serialized and deserialized) by the serializer,
-the `ReflectionBasedAutoSerializer`, it cannot, unlike `MappingPdxSerializer`, perform the following:
+it cannot, unlike `MappingPdxSerializer`, perform the following:
 
-* Register custom `PdxSerializer` objects per entity field and property names and types.
+* Register custom `PdxSerializer` objects per entity field or property names and types.
 * Conveniently identifies ID properties.
 * Automatically handles read-only properties.
 * Automatically handles transient properties.
-* Allows more robust type filtering in a `null`-safe manner (for example, not limited to
+* Allows more robust type filtering in a `null` and type-safe manner (for example, not limited to
-only expressing types using regex).
+only expressing types with regex).
 
 We now explore each feature of the `MappingPdxSerializer` in a bit more detail.
 
 [[mapping.pdx-serializer.custom-serialization]]
 === Custom PdxSerializer Registration
 
-The `MappingPdxSerializer` gives you the ability to register custom `PdxSerializers` based on an entity's
+The `MappingPdxSerializer` gives you the ability to register custom `PdxSerializers` based on an entity's field
-field and property names and types.
+or property names and types.
 
-For instance, suppose you have defined an entity type modeling a `User` as follows:
+For example, suppose you have defined an entity type modeling a `User` as follows:
 
 [source,java]
 ----
-package example.app.auth.model;
+package example.app.security.auth.model;
 
 public class User {
 
@@ -196,10 +196,10 @@ public class User {
 ----
 
 While the user's name probably does not require any special logic to serialize the value, serializing the password
-might require additional logic to handle the sensitive nature of the field or property.
+on the other hand might require additional logic to handle the sensitive nature of the field or property.
 
 Perhaps you want to protect the password when sending the value over the network, between a client and a server,
-and you only want to store the salted hash. When using the `MappingPdxSerializer`, you can register
+beyond TLS alone, and you only want to store the salted hash. When using the `MappingPdxSerializer`, you can register
 a custom `PdxSerializer` to handle the user's password, as follows:
 
 .Registering custom `PdxSerializers` by POJO field/property type
@@ -212,12 +212,13 @@ customPdxSerializers.put(Password.class, new SaltedHashPasswordPdxSerializer());
 
 mappingPdxSerializer.setCustomPdxSerializers(customPdxSerializers);
 ----
+====
 
 After registering the application-defined `SaltedHashPasswordPdxSerializer` instance with the `Password`
-application domain model type, the `MappingPdxSerializer` consults the custom `PdxSerializer` to serialize
+application domain model type, the `MappingPdxSerializer` will then consult the custom `PdxSerializer`
-and deserialize all `Password` objects regardless of the containing object (for example, `User`).
+to serialize and deserialize all `Password` objects regardless of the containing object (for example, `User`).
 
-However, suppose you want to customize the serialization of only `Passwords` on `User` objects.
+However, suppose you want to customize the serialization of `Passwords` only on `User` objects.
 To do so, you can register the custom `PdxSerializer` for the `User` type by specifying the fully qualified name
 of the `Class's` field or property, as the following example shows:
 
@@ -227,12 +228,13 @@ of the `Class's` field or property, as the following example shows:
 ----
 Map<?, PdxSerializer> customPdxSerializers = new HashMap<>();
 
-customPdxSerializers.put("example.app.auth.model.User.password", new SaltedHashPasswordPdxSerializer());
+customPdxSerializers.put("example.app.security.auth.model.User.password", new SaltedHashPasswordPdxSerializer());
 
 mappingPdxSerializer.setCustomPdxSerializers(customPdxSerializers);
 ----
+====
 
-Notice the use of the fully-qualified field or property name (that is `example.app.auth.model.User.password`)
+Notice the use of the fully-qualified field or property name (that is `example.app.security.auth.model.User.password`)
 as the custom `PdxSerializer` registration key.
 
 NOTE: You could construct the registration key by using a more logical code snippet, such as the following:
@@ -246,6 +248,8 @@ Like {data-store-name}'s `ReflectionBasedAutoSerializer`, {sdg-acronym}'s `Mappi
 determine the identifier of the entity. However, `MappingPdxSerializer` does so by using Spring Data's mapping metadata,
 specifically by finding the entity property designated as the identifier using Spring Data's
 {spring-data-commons-javadoc}/org/springframework/data/annotation/Id.html[`@Id`] annotation.
+Alternatively, any field or property named "`id`", not explicitly annotated with `@Id`, is also designated as
+the entity's identifier.
 
 For example:
 
@@ -270,7 +274,7 @@ when the `PdxSerializer.toData(..)` method is called during serialization.
 What happens when your entity defines a read-only property?
 
 First, it is important to understand what a "`read-only`" property is.  If you define a POJO by following the
-http://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html[JavaBeans]specification (as Spring does),
+http://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html[JavaBeans] specification (as Spring does),
 you might define a POJO with a read-only property, as follows:
 
 [source,java]
@@ -289,29 +293,30 @@ class ApplicationDomainType {
 }
 ----
 
-The `readOnly` property is "`read-only`" because it does not provide a setter method. It has only a getter method.
+The `readOnly` property is read-only because it does not provide a setter method. It only has a getter method.
-In this case, the `readOnly` property (not to be confused with the `readOnly` `DomainType` field) is considered
+In this case, the `readOnly` property (not to be confused with the `readOnly` `DomainType` field)
-"`read-only`".
+is considered read-only.
 
-As a result, the `MappingPdxSerializer` does not try to write this value back when populating an instance of
+As a result, the `MappingPdxSerializer` will not try to set a value for this property when populating an instance of
-`DomainType` in the `PdxSerializer.fromData(:Class<?>, :PdxReader)` method.
+`ApplicationDomainType` in the `PdxSerializer.fromData(:Class<ApplicationDomainType>, :PdxReader)` method
+during deserialization, particularly if a value is present in the PDX serialized bytes.
 
 This is useful in situations where you might be returning a view or projection of some entity type and you only want
-to write state that is writable. Perhaps the view or projection of the entity is based on authorization or some other
+to set state that is writable. Perhaps the view or projection of the entity is based on authorization or some other
-criteria. The point is that you can leverage this feature as is appropriate for your application's use cases
+criteria. The point is, you can leverage this feature as is appropriate for your application's use cases
-and requirements. If you want the field or property to always be written, you can define a setter.
+and requirements. If you want the field or property to always be written, simply define a setter method.
 
 [[mapping.pdx-serializer.transient-properties]]
 === Mapping Transient Properties
 
 Likewise, what happens when your entity defines `transient` properties?
 
-You would expect the `transient` fields or properties of your entity not to be serialized to the stream of PDX bytes
+You would expect the `transient` fields or properties of your entity not to be serialized to PDX when serializing
-when serializing the entity. That is exactly what happens, unlike {data-store-name}'s own `ReflectionBasedAutoSerializer`,
+the entity. That is exactly what happens, unlike {data-store-name}'s own `ReflectionBasedAutoSerializer`,
-which serializes everything accessible from the object through Java reflection.
+which serializes everything accessible from the object through Java Reflection.
 
-The `MappingPdxSerializer` does not serialize any fields or properties that are qualified as being transient either
+The `MappingPdxSerializer` will not serialize any fields or properties that are qualified as being transient, either
-by using Java's `transient` keyword (in the case of fields) or by using the
+by using Java's own `transient` keyword (in the case of class instance fields) or by using the
 {spring-data-commons-javadoc}/org/springframework/data/annotation/Transient.html[`@Transient`]
 Spring Data annotation on either fields or properties.
 
@@ -340,21 +345,21 @@ class Process {
 }
 ----
 
-Neither the `Process` `id` field nor the readable `hostname` property are written to the PDX serialized bytes.
+Neither the `Process` `id` field nor the readable `hostname` property are written to PDX.
 
 [[mapping.pdx-serializer.type-filtering]]
-=== Filtering by Class types
+=== Filtering by Class Type
 
 Similar to {data-store-name}'s `ReflectionBasedAutoSerializer`, {sdg-acronym}'s `MappingPdxSerializer` lets you filter
-the types of objects that the `MappingPdxSerializer` serializes and deserializes.
+the types of objects that are serialized and deserialized.
 
 However, unlike {data-store-name}'s `ReflectionBasedAutoSerializer`, which uses complex regular expressions to express
 which types the serializer handles, {sdg-acronym}'s `MappingPdxSerializer` uses the much more robust
 https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html[`java.util.function.Predicate`] interface
 and API to express type-matching criteria.
 
-If you like to use regular expressions, you can implement a `Predicate` by using
+TIP: If you like to use regular expressions, you can implement a `Predicate` using Java's
-Java's https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html[regular expression support].
+https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html[regular expression support].
 
 The nice part about Java's `Predicate` interface is that you can compose `Predicates` by using convenient
 and appropriate API methods, including:
@@ -362,21 +367,75 @@ https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html#and-
 https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html#or-java.util.function.Predicate-[`or(:Predicate)`],
 and https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html#negate--[`negate()`].
 
-The following example shows the `Predicate` API in use:
+The following example shows the `Predicate` API in action:
 
 [source,java]
 ----
 Predicate<Class<?>> customerTypes =
-  type -> Customer.class.getPackage().getName().startsWith(type.getName());
+  type -> Customer.class.getPackage().getName().startsWith(type.getName()); // Include all types in the same package as `Customer`
 
-Predicate typeFilters = customerTypes
+Predicate includedTypes = customerTypes
-  .or(type -> User.class.isAssignble(type)) // Include User sub-types (e.g. Admin, Guest, etc)
+  .or(type -> User.class.isAssignble(type)); // Additionally, include User sub-types (e.g. Admin, Guest, etc)
-  .and(type -> !Reference.class.getPackage(type.getPackage()); // Exclude all Reference types
 
-mappingPdxSerializer.setTypeFilters(typeFilters);
+mappingPdxSerializer.setIncludeTypeFilters(includedTypes);
+
+mappingPdxSerializer.setExcludeTypeFilters(
+  type -> !Reference.class.getPackage(type.getPackage()); // Exclude Reference types
 ----
 
-NOTE: In addition to setting your own type filtering `Predicates`, SDG's `MappingPdxSerializer` now automatically
+NOTE: Any `Class` object passed to your `Predicate` is guaranteed not to be `null`.
-registers pre-defined `Predicates` that filter types from the `org.apache.geode` package along with `null` objects
+
-when calling `PdxSerializer.toData(:Object, :PdxWriter)` or `null` `Class` types when calling
+{sdg-acronym}'s `MappingPdxSerializer` includes support for both include and exclude class type filters.
-`PdxSerializer.fromData(:Class<?>, :PdxReader)` methods.
+
+[[mapping.pdx-serializer.type-filtering.execludes]]
+==== Exclude Type Filtering
+
+By default, {sdg-acronym}'s `MappingPdxSerializer`  registers pre-defined `Predicates` that filter, or exclude types
+from the folliowing packages:
+
+* `java.*`
+* `com.gemstone.gemfire.*`
+* `org.apache.geode.*`
+* `org.springframework.*`
+
+In addition, the `MappingPdxSerializer`  filters `null` objects when calling `PdxSerializer.toData(:Object, :PdxWriter)`
+and `null` class types when calling `PdxSerializer.fromData(:Class<?>, :PdxReader)` methods.
+
+It is very easy to add exclusions for other class types, or an entire package of types, by simply defining a `Predicate`
+and adding it to the `MappingPdxSerializer` as shown earlier.
+
+The `MappingPdxSerializer.setExcludeTypeFilters(:Predicate<Class<?>>)` method is additive, meaning it composes
+your application-defined type filters with the existing, pre-defined type filter `Predicates` indicated above
+using the `Predicate.and(:Predicate<Class<?>>)` method.
+
+However, what if you want to include a class type (for example, `java.security Principal`) implicitly excluded by
+the exclude type filters?  See <<mapping.pdx-serializer.type-filtering.includes>>.
+
+[[mapping.pdx-serializer.type-filtering.includes]]
+==== Include Type Filtering
+
+If you want to include a class type explicitly, or override a class type filter that implicitly excludes a class type
+required by your application (for example, `java.security.Principal`, which is excluded by default with the `java.*`
+package exclude type filter on `MappingPdxSerializer`), then just define the appropriate `Predicate` and add it to
+the serializer using `MappingPdxSerializer.setIncludeTypeFilters(:Predicate<Class<?>>)` method, as follows:
+
+[source,java]
+----
+Predicate<Class<?>> principalTypeFilter =
+  type -> java.security.Principal.class.isAssignableFrom(type);
+
+mappingPdxSerializer.setIncludeTypeFilters(principalTypeFilters);
+----
+
+Again, the `MappingPdxSerializer.setIncludeTypeFilters(:Predicate<Class<?>>)` method,
+like `setExcludeTypeFilters(:Predicate<Class<?>>)`, is additive and therefore composes any passed type filter
+using `Predicate.or(:Predicate<Class<?>>)`.  This means you may call `setIncludeTypeFilters(:Predicate<Class<?>>)`
+as many time as necessary.
+
+When include type filters are present, then the `MappingPdxSerializer` makes a decision of whether to de/serialize
+an instance of a class type when the class type is either not implicitly excluded OR when the class type
+is explicitly included, whichever returns true.  Then, an instance of the class type will be serialized
+or deserialized appropriately.
+
+For example, when a type filter of `Predicate<Class<Principal>>` is explicitly registered as shown previously,
+it cancels out the implicit exclude type filter on `java.*` package types.

src/main/java/org/springframework/data/gemfire/mapping/MappingPdxSerializer.java

@@ -473,6 +473,7 @@ public class MappingPdxSerializer implements PdxSerializer, ApplicationContextAw
 	 * @see java.lang.Object
 	 * @see java.lang.Class
 	 */
+	@SuppressWarnings("unchecked")
 	Object doFromData(Class<?> type, PdxReader reader) {
 
 		GemfirePersistentEntity<?> entity = getPersistentEntity(type);