From 5b608ea8434cf44dac90a10c23bd40e5e3ce10f9 Mon Sep 17 00:00:00 2001 From: David Barnes Date: Thu, 11 Jun 2020 14:58:56 -0700 Subject: [PATCH 1/2] Update C++ serialization example --- .../pdx-serializable-examples.html.md.erb | 4 +- .../pdxserializable-interface.html.md.erb | 114 +++++++----------- 2 files changed, 45 insertions(+), 73 deletions(-) diff --git a/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdx-serializable-examples.html.md.erb b/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdx-serializable-examples.html.md.erb index cf613ddbc6..bd0607d373 100644 --- a/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdx-serializable-examples.html.md.erb +++ b/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdx-serializable-examples.html.md.erb @@ -20,7 +20,7 @@ limitations under the License. --> The native client release contains an example showing how a client application -can register for serialization of custom objects using the C++ PdxSerializable interface. +can register for serialization of custom objects using the C++ PdxSerializable abstract class. The example is located in `examples/cpp/pdxserializable`. @@ -52,7 +52,7 @@ The example performs a sequence of operations, displaying simple log entries as This section contains code snippets showing highlights of the C++ PdxSerialiable example. They are not intended for cut-and-paste execution. For the complete source, see the example source directory. -The C++ example defines a PdxSerializable class called `Order` that inherits from the `PdxSerializable` interface. +The C++ example defines a PdxSerializable class called `Order` that inherits from the `PdxSerializable` abstract class. An `Order` object contains three fields: - an integer `order_id` diff --git a/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdxserializable-interface.html.md.erb b/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdxserializable-interface.html.md.erb index eecc5662d9..737f3c9bfe 100644 --- a/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdxserializable-interface.html.md.erb +++ b/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdxserializable-interface.html.md.erb @@ -27,88 +27,60 @@ A domain class should serialize and de-serialize all its member fields in the sa Use this procedure to program your domain object for PDX serialization using the `PdxSerializable` abstract class. -1. In your domain class, implement `PdxSerializable`. Example: +1. In your domain class, implement `PdxSerializable`. For example: ``` pre - class PdxObject: public PdxSerializable + class Order : public PdxSerializable { ``` -2. Program the `toData` function to serialize your object as required by your application. -

+2. Program the `toData` method to serialize your object as required by your application. (See `markIdentityField` in a later step for an optimization that you can apply to this code sample.) + + ``` cpp + void Order::toData(PdxWriter& pdxWriter) const { + pdxWriter.writeInt(ORDER_ID_KEY_, order_id_); + pdxWriter.writeString(NAME_KEY_, name_); + pdxWriter.writeShort(QUANTITY_KEY_, quantity_); + } + ``` + If you also use PDX serialization in Java or .NET for the object, serialize the object in the same way for each language. Serialize the same fields in the same order and mark the same identity fields. 3. Program the `fromData` method to read your data fields from the serialized form into the object's fields. -

- In your `fromData` implementation, use the same name as you did in `toData` and call the read operations in the same order as you called the write operations in your `toData` implementation. -4. Optionally, program your domain object's `hashCode` and equality methods. -

- Use the `markIdentityField` method to indicate that the given field name should be included in `hashCode` and equality checks of this object on a server. -

- The fields that are marked as identity fields are used to generate the `hashCode` and equality methods of PdxInstance. Because of this, the identity fields should themselves either be primitives, or implement `hashCode` and equals. -

- If no fields are set as identity fields, then all fields will be used in `hashCode` and equality checks. The identity fields should make marked after they are written using a `write*` method. - -For example: - -``` cpp -class PdxObject: public PdxSerializable { + ```cpp + void Order::fromData(PdxReader& pdxReader) { + order_id_ = pdxReader.readInt(ORDER_ID_KEY_); + name_ = pdxReader.readString(NAME_KEY_); + quantity_ = pdxReader.readShort(QUANTITY_KEY_); + } + ``` -private: - uint32_t m_id; - char* m_str; + In your `fromData` implementation, use the same name as you did in `toData` and call the read operations in the same order as you called the write operations in your `toData` implementation. -public: - PdxObject(){}; - PdxObject(uint32_t id, char* str); - virtual ~PdxObject(); +4. Optionally, program your domain object's `hashCode` and equality methods. When you do so, you can optimize those methods by specifying the _identity fields_ + to be used in comparisons. +

+ If no fields are set as identity fields, then all fields will be used in `hashCode` and equality checks, so marking identity fields improves the efficiency + of hashing and equality operations. +

+ Use the `markIdentityField` method to indicate that the given field name should be included in `hashCode` and equality checks of this object on a server. + It is important that the fields used by your equality method and `hashCode` implementations are the same fields that you mark as identity fields. +

+ Expanding the code sample from the description of the `toData` method, above: - uint32_t getID() { - return m_id; - } + ``` cpp + void Order::toData(PdxWriter& pdxWriter) const { + pdxWriter.writeInt(ORDER_ID_KEY_, order_id_); + pdxWriter.markIdentityField(ORDER_ID_KEY_); - char* getStr(){ - return m_str; - } + pdxWriter.writeString(NAME_KEY_, name_); + pdxWriter.markIdentityField(NAME_KEY_); - virtual void toData(PdxWriterPtr pw) const; - virtual void fromData(PdxReaderPtr pr); - CacheableStringPtr toString() const; - virtual char* getClassName() const; - static Cacheable* createDeserializable() { - return new PdxObject(); + pdxWriter.writeShort(QUANTITY_KEY_, quantity_); + pdxWriter.markIdentityField(QUANTITY_KEY_); } -}; - -PdxObject::PdxObject(uint32_t i, char* str) { - m_id = i; - m_str = str; -} - -PdxObject::~PdxObject() { -} - -void PdxObject::toData( PdxWriterPtr pw ) const { - pw->writeInt("id", m_id); - pw->markIdentityField("id"); - pw->writeString("str", m_str); -} - -void PdxObject::fromData( PdxReaderPtr pr ) -{ - m_id = pr->readInt("id"); - m_str = pr->readString("str"); -} - -char* getClassName() const{ -{ - return "com.example.PdxType"; -} - -CacheableStringPtr PdxObject::toString() const { - char idbuf[1024]; - sprintf(idbuf,"PdxObject: [ ID=%d ]",m_id); - return CacheableString::create( idbuf ); -} -``` - + ``` + The fields that are marked as identity fields are used to generate the `hashCode` and equality + methods of PdxInstance. Because of this, the identity fields should themselves either be primitives, + or implement `hashCode` and equals. The identity fields should be marked after they are written + using a `write*` method. From eac9324da1c95c0479f6ee229de57a409b2bd821 Mon Sep 17 00:00:00 2001 From: David Barnes Date: Fri, 12 Jun 2020 09:55:52 -0700 Subject: [PATCH 2/2] Incorporate reviewer suggestions --- .../pdxserializable-interface.html.md.erb | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdxserializable-interface.html.md.erb b/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdxserializable-interface.html.md.erb index 737f3c9bfe..4f09837dfe 100644 --- a/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdxserializable-interface.html.md.erb +++ b/docs/geode-native-docs-cpp/serialization/cpp-serialization/pdxserializable-interface.html.md.erb @@ -23,7 +23,7 @@ When you write objects using PDX serialization, they are distributed to the serv Domain classes need to inherit the `PdxSerializable` abstract class to serialize and de-serialize the object. When you run queries against the objects on the servers, only the fields you specify are deserialized. -A domain class should serialize and de-serialize all its member fields in the same order in its `toData` and `fromData` methods. +A domain class should serialize and de-serialize all its member fields in the same order in its `toData` and `fromData` functions. Use this procedure to program your domain object for PDX serialization using the `PdxSerializable` abstract class. @@ -33,7 +33,7 @@ Use this procedure to program your domain object for PDX serialization using the class Order : public PdxSerializable { ``` -2. Program the `toData` method to serialize your object as required by your application. (See `markIdentityField` in a later step for an optimization that you can apply to this code sample.) +2. Program the `toData` function to serialize your object as required by your application. (See `markIdentityField` in a later step for an optimization that you can apply to this code sample.) ``` cpp void Order::toData(PdxWriter& pdxWriter) const { @@ -45,7 +45,7 @@ Use this procedure to program your domain object for PDX serialization using the If you also use PDX serialization in Java or .NET for the object, serialize the object in the same way for each language. Serialize the same fields in the same order and mark the same identity fields. -3. Program the `fromData` method to read your data fields from the serialized form into the object's fields. +3. Program the `fromData` function to read your data fields from the serialized form into the object's fields. ```cpp void Order::fromData(PdxReader& pdxReader) { @@ -57,16 +57,22 @@ Use this procedure to program your domain object for PDX serialization using the In your `fromData` implementation, use the same name as you did in `toData` and call the read operations in the same order as you called the write operations in your `toData` implementation. -4. Optionally, program your domain object's `hashCode` and equality methods. When you do so, you can optimize those methods by specifying the _identity fields_ +4. Optionally, program your domain object's `hashCode` and equality functions. When you do so, you can optimize those functions by specifying the _identity fields_ to be used in comparisons. -

- If no fields are set as identity fields, then all fields will be used in `hashCode` and equality checks, so marking identity fields improves the efficiency +
+ - Marked identity fields are used to generate the `hashCode` and equality functions of PdxInstance, so the identity fields should themselves either be primitives, + or implement `hashCode` and `equals`. +
+ - The `markIdentityField` function indicates that the given field name should be included in `hashCode` and equality checks of this object on a server. +
+ - Invoke the `markIdentityField` function directly after the identity field's `write*` function. +
+ - If no fields are set as identity fields, then all fields will be used in `hashCode` and equality checks, so marking identity fields improves the efficiency of hashing and equality operations. -

- Use the `markIdentityField` method to indicate that the given field name should be included in `hashCode` and equality checks of this object on a server. - It is important that the fields used by your equality method and `hashCode` implementations are the same fields that you mark as identity fields. -

- Expanding the code sample from the description of the `toData` method, above: +
+ - It is important that the fields used by your equality function and `hashCode` implementations are the same fields that you mark as identity fields. + + This code sample expands the sample from the description of the `toData` function, above, to illustrate the use of `markIdentityField`: ``` cpp void Order::toData(PdxWriter& pdxWriter) const { @@ -80,7 +86,3 @@ Use this procedure to program your domain object for PDX serialization using the pdxWriter.markIdentityField(QUANTITY_KEY_); } ``` - The fields that are marked as identity fields are used to generate the `hashCode` and equality - methods of PdxInstance. Because of this, the identity fields should themselves either be primitives, - or implement `hashCode` and equals. The identity fields should be marked after they are written - using a `write*` method.