ReflectionBasedAutoSerializer (Apache Geode 1.7.0)
Date: 2018-09-27

org.apache.geode.pdx

## Class ReflectionBasedAutoSerializer

- java.lang.Object
- - org.apache.geode.pdx.ReflectionBasedAutoSerializer

- All Implemented Interfaces:
    Declarable, PdxSerializer

      public class ReflectionBasedAutoSerializer
      extends java.lang.Object
      implements PdxSerializer, Declarable

  This class uses Java reflection in conjunction with `PdxSerialzer` to perform automatic serialization of domain objects. The implication is that the domain classes do not need to implement the `PdxSerializable` interface.

  This implementation will serialize all relevant fields

  For example:

       Cache c = new CacheFactory().set("cache-xml-file", cacheXmlFileName)
           .setPdxSerializer(new ReflectionBasedAutoSerializer("com.foo.DomainObject")).create();

  In this example `DomainObject` would not need to implement `PdxSerializable` to be serialized.

  The equivalent `cache.xml` entries might be as follows:

       <pdx>
         <pdx-serializer>
           <class-name>
             org.apache.geode.pdx.ReflectionBasedAutoSerializer
           </class-name>
           <parameter name="classes">
             <string> com.company.domain.DomainObject </string>
           </parameter>
         </pdx-serializer>
       </pdx>

  See `reconfigure` for additional details on the format of the parameter string.
  Since:
    GemFire 6.6

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ReflectionBasedAutoSerializer()` Default constructor primarily used during declarative configuration via the cache.xml file.
    `ReflectionBasedAutoSerializer(boolean checkPortability, java.lang.String... patterns)` Constructor which takes a list of class name patterns which are to be auto-serialized.
    `ReflectionBasedAutoSerializer(java.util.List<java.lang.String> classes)` Deprecated. as of 6.6.2 use ReflectionBasedAutoSerializer(String...) instead.
    `ReflectionBasedAutoSerializer(java.lang.String... patterns)` Constructor which takes a list of class name patterns which are to be auto-serialized.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `fromData(java.lang.Class<?> clazz, PdxReader reader)` Method implemented from `PdxSerializer` which performs object de-serialization.
    `java.util.Properties` | `getConfig()` Return a `Properties` object with a representation of the current config.
    `java.lang.String` | `getFieldName(java.lang.reflect.Field f, java.lang.Class<?> clazz)` Controls the field name that will be used in pdx for a field being auto serialized.
    `FieldType` | `getFieldType(java.lang.reflect.Field f, java.lang.Class<?> clazz)` Controls what pdx field type will be used when auto serializing.
    `java.lang.Object` | `getManager()` For internal use only.
    `RegionService` | `getRegionService()` Returns the cache that this serializer is installed on.
    `void` | `init(java.util.Properties props)` Deprecated. as of Geode 1.5 use initialize instead
    `void` | `initialize(Cache cache, java.util.Properties props)` Used for declarative class initialization from cache.xml.
    `boolean` | `isClassAutoSerialized(java.lang.Class<?> clazz)` Controls what classes will be auto serialized by this serializer.
    `boolean` | `isFieldIncluded(java.lang.reflect.Field f, java.lang.Class<?> clazz)` Controls what fields of a class will be auto serialized by this serializer.
    `boolean` | `isIdentityField(java.lang.reflect.Field f, java.lang.Class<?> clazz)` Controls what fields of a class that is auto serialized will be marked as pdx identity fields.
    `java.lang.Object` | `readTransform(java.lang.reflect.Field f, java.lang.Class<?> clazz, java.lang.Object serializedValue)` Controls what field value is read during auto deserialization.
    `void` | `reconfigure(boolean checkPortability, java.lang.String... patterns)` Method to reconfigure this serializer.
    `void` | `reconfigure(java.lang.String... patterns)` Method to reconfigure this serializer.
    `void` | `setSerializableClasses(java.util.List<java.lang.String> patterns)` Deprecated. as of 6.6.2 use `reconfigure(String...)` instead.
    `boolean` | `toData(java.lang.Object obj, PdxWriter writer)` Method implemented from `PdxSerializer` which performs object serialization.
    `boolean` | `transformFieldValue(java.lang.reflect.Field f, java.lang.Class<?> clazz)` Controls if a pdx field's value can be transformed during serialization.
    `java.lang.Object` | `writeTransform(java.lang.reflect.Field f, java.lang.Class<?> clazz, java.lang.Object originalValue)` Controls what field value is written during auto serialization.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ReflectionBasedAutoSerializer

          public ReflectionBasedAutoSerializer()

      Default constructor primarily used during declarative configuration via the cache.xml file. Instances created with this constructor will not match any classes so use `ReflectionBasedAutoSerializer(String...)` instead.

    - #### ReflectionBasedAutoSerializer

          public ReflectionBasedAutoSerializer(java.util.List<java.lang.String> classes)

      Deprecated. as of 6.6.2 use ReflectionBasedAutoSerializer(String...) instead.
      Constructor which takes a list of class name patterns which are to be auto-serialized. Portability of serialization will not be checked.

      Each string in the list represents a definition in the following form:

             <class pattern>#identity=<identity field pattern>#exclude=<exclude field pattern>

      The hash (#) characters are separators and are not part of the parameter name. An example would be:

             com.company.DomainObject.*#identity=id.*#exclude=creationDate

      This would select all classes with a class name beginning with `com.company.DomainObject` and would select as PDX identity fields any fields beginning with `id` and would not serialize the field called `creationDate`.

      There is no association between the the identity and exclude options, so the above example could also be expressed as:

             com.company.DomainObject.*#identity=id.*
             com.company.DomainObject.*#exclude=creationDate

      Note that all defined patterns are used when determining whether a field should be considered as an identity field or should be excluded. Thus the order of the patterns is not relevant.
      Parameters:
        `classes` - the patterns which are matched against domain class names to determine whether they should be serialized

    - #### ReflectionBasedAutoSerializer

          public ReflectionBasedAutoSerializer(java.lang.String... patterns)

      Constructor which takes a list of class name patterns which are to be auto-serialized. Portability of serialization will not be checked.

      Each string in the list represents a definition in the following form:

             <class pattern>#identity=<identity field pattern>#exclude=<exclude field pattern>

      The hash (#) characters are separators and are not part of the parameter name. An example would be:

             com.company.DomainObject.*#identity=id.*#exclude=creationDate

      This would select all classes with a class name beginning with `com.company.DomainObject` and would select as PDX identity fields any fields beginning with `id` and would not serialize the field called `creationDate`.

      There is no association between the the identity and exclude options, so the above example could also be expressed as:

             com.company.DomainObject.*#identity=id.*
             com.company.DomainObject.*#exclude=creationDate

      Note that all defined patterns are used when determining whether a field should be considered as an identity field or should be excluded. Thus the order of the patterns is not relevant.
      Parameters:
        `patterns` - the patterns which are matched against domain class names to determine whether they should be serialized
      Since:
        GemFire 6.6.2

    - #### ReflectionBasedAutoSerializer

          public ReflectionBasedAutoSerializer(boolean checkPortability,
                                               java.lang.String... patterns)

      Constructor which takes a list of class name patterns which are to be auto-serialized.

      Each string in the list represents a definition in the following form:

             <class pattern>#identity=<identity field pattern>#exclude=<exclude field pattern>

      The hash (#) characters are separators and are not part of the parameter name. An example would be:

             com.company.DomainObject.*#identity=id.*#exclude=creationDate

      This would select all classes with a class name beginning with `com.company.DomainObject` and would select as PDX identity fields any fields beginning with `id` and would not serialize the field called `creationDate`.

      There is no association between the the identity and exclude options, so the above example could also be expressed as:

             com.company.DomainObject.*#identity=id.*
             com.company.DomainObject.*#exclude=creationDate

      Note that all defined patterns are used when determining whether a field should be considered as an identity field or should be excluded. Thus the order of the patterns is not relevant.
      Parameters:
        `checkPortability` - if `true` then an serialization done by this serializer will throw an exception if the object it not portable to non-java languages.
        `patterns` - the patterns which are matched against domain class names to determine whether they should be serialized
      Since:
        GemFire 6.6.2

  - ### Method Detail

    - #### setSerializableClasses

          public void setSerializableClasses(java.util.List<java.lang.String> patterns)

      Deprecated. as of 6.6.2 use `reconfigure(String...)` instead.
      Method to configure classes to consider for serialization, to set any identity fields and to define any fields to exclude from serialization.

      Each string in the list represents a definition in the following form:

             <class pattern>#identity=<identity field pattern>#exclude=<exclude field pattern>

      The hash (#) characters are separators and are not part of the parameter name. An example would be:

             com.company.DomainObject.*#identity=id.*#exclude=creationDate

      This would select all classes with a class name beginning with `com.company.DomainObject` and would select as PDX identity fields any fields beginning with `id` and would not serialize the field called `creationDate`.

      There is no association between the the identity and exclude options, so the above example could also be expressed as:

             com.company.DomainObject.*#identity=id.*
             com.company.DomainObject.*#exclude=creationDate

      Note that all defined patterns are used when determining whether a field should be considered as an identity field or should be excluded. Thus the order of the patterns is not relevant.
      Parameters:
        `patterns` - the list of definitions to apply

    - #### reconfigure

          public void reconfigure(java.lang.String... patterns)

      Method to reconfigure this serializer. Any previous configuration is cleared. The serializer will not check for portable serialization.

      Each string in the list represents a definition in the following form:

             <class pattern>#identity=<identity field pattern>#exclude=<exclude field pattern>

      The hash (#) characters are separators and are not part of the parameter name. An example would be:

             com.company.DomainObject.*#identity=id.*#exclude=creationDate

      This would select all classes with a class name beginning with `com.company.DomainObject` and would select as PDX identity fields any fields beginning with `id` and would not serialize the field called `creationDate`.

      There is no association between the the identity and exclude options, so the above example could also be expressed as:

             com.company.DomainObject.*#identity=id.*
             com.company.DomainObject.*#exclude=creationDate

      Note that all defined patterns are used when determining whether a field should be considered as an identity field or should be excluded. Thus the order of the patterns is not relevant.
      Parameters:
        `patterns` - the definitions to apply
      Since:
        GemFire 6.6.2

    - #### reconfigure

          public void reconfigure(boolean checkPortability,
                                  java.lang.String... patterns)

      Method to reconfigure this serializer. Any previous configuration is cleared.

      Each string in the list represents a definition in the following form:

             <class pattern>#identity=<identity field pattern>#exclude=<exclude field pattern>

      The hash (#) characters are separators and are not part of the parameter name. An example would be:

             com.company.DomainObject.*#identity=id.*#exclude=creationDate

      This would select all classes with a class name beginning with `com.company.DomainObject` and would select as PDX identity fields any fields beginning with `id` and would not serialize the field called `creationDate`.

      There is no association between the the identity and exclude options, so the above example could also be expressed as:

             com.company.DomainObject.*#identity=id.*
             com.company.DomainObject.*#exclude=creationDate

      Note that all defined patterns are used when determining whether a field should be considered as an identity field or should be excluded. Thus the order of the patterns is not relevant.
      Parameters:
        `patterns` - the definitions to apply
        `checkPortability` - if `true` then an serialization done by this serializer will throw an exception if the object it not portable to non-java languages.
      Since:
        GemFire 6.6.2

    - #### toData

          public boolean toData(java.lang.Object obj,
                                PdxWriter writer)

      Method implemented from `PdxSerializer` which performs object serialization.
      Specified by:
        `toData` in interface `PdxSerializer`
      Parameters:
        `obj` - the object to serialize
        `writer` - the `PdxWriter` to use when serializing this object
      Returns:
        `true` if the object was serialized, `false` otherwise

    - #### fromData

          public java.lang.Object fromData(java.lang.Class<?> clazz,
                                           PdxReader reader)

      Method implemented from `PdxSerializer` which performs object de-serialization.
      Specified by:
        `fromData` in interface `PdxSerializer`
      Parameters:
        `clazz` - the class of the object to re-create
        `reader` - the `PdxReader` to use when creating this object
      Returns:
        the deserialized object if this serializer handles the given class, null otherwise.

    - #### init

          public void init(java.util.Properties props)

      Deprecated. as of Geode 1.5 use initialize instead
      Used for declarative class initialization from cache.xml. The following property may be specified:
      - classes - a comma-delimited list of strings which represent the patterns used to select classes for serialization, patterns to select identity fields and patterns to exclude fields. See `reconfigure` for specifics.
      - check-portability - if true then an exception will be thrown if an attempt to serialize data that is not portable to .NET is made.
      Specified by:
        `init` in interface `Declarable`
      Parameters:
        `props` - properties used to configure the auto serializer

    - #### initialize

          public void initialize(Cache cache,
                                 java.util.Properties props)

      Used for declarative class initialization from cache.xml. The following property may be specified:
      - classes - a comma-delimited list of strings which represent the patterns used to select classes for serialization, patterns to select identity fields and patterns to exclude fields. See `reconfigure` for specifics.
      - check-portability - if true then an exception will be thrown if an attempt to serialize data that is not portable to .NET is made.
      Specified by:
        `initialize` in interface `Declarable`
      Parameters:
        `cache` - the cache that owns this serializer
        `props` - properties used to configure the auto serializer
      Since:
        Geode 1.5

    - #### getConfig

          public java.util.Properties getConfig()

      Return a `Properties` object with a representation of the current config. Depending on how this `ReflectionBasedAutoSerializer` was configured, the returned property value will have the correct semantics but may differ from the the original configuration string.
      Returns:
        a `Properties` object

    - #### isClassAutoSerialized

          public boolean isClassAutoSerialized(java.lang.Class<?> clazz)

      Controls what classes will be auto serialized by this serializer. Override this method to customize what classes will be auto serialized.

      The default implementation:

      - only serializes classes whose name matches one of the patterns
      - excludes classes whose package begins with "org.apache.", "java.", or "javax." unless the system property "gemfire.auto.serialization.no.hardcoded.excludes" is set to "true".
      - excludes classes that do not have a public no-arg constructor
      - excludes enum classes
      - excludes classes that require standard java serialization. A class requires standard java serialization if it extends Externalizable or if it extends Serializable and has either a private writeObject method or a writeReplace method as defined by the java serialization specification.

      This method is only called the first time it sees a new class. The result will be remembered and used the next time the same class is seen.

      Parameters:
        `clazz` - the class that is being considered for auto serialization.
      Returns:
        true if instances of the class should be auto serialized; false if not.
      Since:
        GemFire 6.6.2

    - #### isFieldIncluded

          public boolean isFieldIncluded(java.lang.reflect.Field f,
                                         java.lang.Class<?> clazz)

      Controls what fields of a class will be auto serialized by this serializer. Override this method to customize what fields of a class will be auto serialized.

      The default implementation:

      - excludes transient fields
      - excludes static fields
      - excludes any fields that match an "#exclude=" pattern.
      All other fields are included.

      This method is only called the first time it sees a new class. The result will be remembered and used the next time the same class is seen.

      Parameters:
        `f` - the field being considered for serialization
        `clazz` - the original class being serialized that owns this field. Note that this field may have been inherited from a super class by this class. If you want to find the class that declared this field use `Field.getDeclaringClass()`.
      Returns:
        true if the field should be serialized as a pdx field; false if it should be ignored.
      Since:
        GemFire 6.6.2

    - #### getFieldName

          public java.lang.String getFieldName(java.lang.reflect.Field f,
                                               java.lang.Class<?> clazz)

      Controls the field name that will be used in pdx for a field being auto serialized. Override this method to customize the field names that will be generated by auto serialization. It allows you to convert a local, language dependent name, to a more portable name. The returned name is the one that will show up in a `PdxInstance` and that one that will need to be used to access the field when doing a query.

      The default implementation returns the name obtained from `f`.

      This method is only called the first time it sees a new class. The result will be remembered and used the next time the same class is seen.

      Parameters:
        `f` - the field whose name is returned.
        `clazz` - the original class being serialized that owns this field. Note that this field may have been inherited from a super class by this class. If you want to find the class that declared this field use `Field.getDeclaringClass()`.
      Returns:
        the name of the field
      Since:
        GemFire 6.6.2

    - #### isIdentityField

          public boolean isIdentityField(java.lang.reflect.Field f,
                                         java.lang.Class<?> clazz)

      Controls what fields of a class that is auto serialized will be marked as pdx identity fields. Override this method to customize what fields of an auto serialized class will be identity fields. Identity fields are used when a `PdxInstance` computes its hash code and checks to see if it is equal to another object.

      The default implementation only marks fields that match an "#identity=" pattern as identity fields.

      This method is only called the first time it sees a new class. The result will be remembered and used the next time the same class is seen.

      Parameters:
        `f` - the field to test to see if it is an identity field.
        `clazz` - the original class being serialized that owns this field. Note that this field may have been inherited from a super class by this class. If you want to find the class that declared this field use `Field.getDeclaringClass()`.
      Returns:
        true if the field should be marked as an identity field; false if not.
      Since:
        GemFire 6.6.2

    - #### getFieldType

          public FieldType getFieldType(java.lang.reflect.Field f,
                                        java.lang.Class<?> clazz)

      Controls what pdx field type will be used when auto serializing. Override this method to customize what pdx field type will be used for a given domain class field.

      The default implementation uses `FieldType.get(Class)` by passing it `Field.getType()`.

      This method is only called the first time it sees a new class. The result will be remembered and used the next time the same class is seen.

      Parameters:
        `f` - the field whose pdx field type needs to be determined
        `clazz` - the original class being serialized that owns this field. Note that this field may have been inherited from a super class by this class. If you want to find the class that declared this field use `Field.getDeclaringClass()`.
      Returns:
        the pdx field type of the given domain class field.
      Since:
        GemFire 6.6.2

    - #### transformFieldValue

          public boolean transformFieldValue(java.lang.reflect.Field f,
                                             java.lang.Class<?> clazz)

      Controls if a pdx field's value can be transformed during serialization. Override this method to customize what fields can have their values transformed. If you return true then you need to also override `writeTransform(java.lang.reflect.Field, java.lang.Class<?>, java.lang.Object)` and `readTransform(java.lang.reflect.Field, java.lang.Class<?>, java.lang.Object)`.

      The default implementation returns false.

      This method is only called the first time it sees a new class. The result will be remembered and used the next time the same class is seen.

      Parameters:
        `f` - the field in question
        `clazz` - the original class being serialized that owns this field. Note that this field may have been inherited from a super class by this class. If you want to find the class that declared this field use `Field.getDeclaringClass()`.
      Returns:
        true if the `writeTransform(java.lang.reflect.Field, java.lang.Class<?>, java.lang.Object)` and `readTransform(java.lang.reflect.Field, java.lang.Class<?>, java.lang.Object)` need to be called when serializing and deserializing this field's value.
      Since:
        GemFire 6.6.2

    - #### writeTransform

          public java.lang.Object writeTransform(java.lang.reflect.Field f,
                                                 java.lang.Class<?> clazz,
                                                 java.lang.Object originalValue)

      Controls what field value is written during auto serialization. Override this method to customize the data that will be written during auto serialization. This method will only be called if `transformFieldValue(java.lang.reflect.Field, java.lang.Class<?>)` returned true.
      Parameters:
        `f` - the field in question
        `clazz` - the original class being serialized that owns this field. Note that this field may have been inherited from a super class by this class. If you want to find the class that declared this field use `Field.getDeclaringClass()`.
        `originalValue` - the value of the field that was read from the domain object.
      Returns:
        the actual value to write for this field. Return `originalValue` if you decide not to transform the value.
      Since:
        GemFire 6.6.2

    - #### readTransform

          public java.lang.Object readTransform(java.lang.reflect.Field f,
                                                java.lang.Class<?> clazz,
                                                java.lang.Object serializedValue)

      Controls what field value is read during auto deserialization. Override this method to customize the data that will be read during auto deserialization. This method will only be called if `transformFieldValue(java.lang.reflect.Field, java.lang.Class<?>)` returned true.
      Parameters:
        `f` - the field in question
        `clazz` - the original class being serialized that owns this field. Note that this field may have been inherited from a super class by this class. If you want to find the class that declared this field use `Field.getDeclaringClass()`.
        `serializedValue` - the value of the field that was serialized for this field.
      Returns:
        the actual value to write for this field. Return `serializedValue` if you decide not to transform the value.
      Since:
        GemFire 6.6.2

    - #### getRegionService

          public RegionService getRegionService()

      Returns the cache that this serializer is installed on. Returns null if it is not installed.
      Since:
        GemFire 6.6.2

    - #### getManager

          public java.lang.Object getManager()

      For internal use only.
      Since:
        GemFire 8.2