This is an automated email from the ASF dual-hosted git repository.
dbarnes pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/geode-native.git
The following commit(s) were added to refs/heads/develop by this push:
new d7e3906 GEODE-4728: update serialization docs - WIP
d7e3906 is described below
commit d7e3906a7687ece7c3ba5312f934e04635010070
Author: Dave Barnes <[email protected]>
AuthorDate: Thu Jul 19 16:45:02 2018 -0700
GEODE-4728: update serialization docs - WIP
---
.../source/subnavs/geode-nc-nav.erb | 7 +-
.../pdxserializable-example.html.md.erb | 165 +++++++++++++++++++++
.../using-pdxserialization.html.md.erb} | 31 ++--
.../serialization/data-serialization.html.md.erb | 51 -------
4 files changed, 180 insertions(+), 74 deletions(-)
diff --git
a/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
b/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
index 2d3491b..f5abcf2 100644
--- a/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
+++ b/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
@@ -68,7 +68,7 @@ limitations under the License.
<a
href="/docs/guide-native/<%=vars.product_version_nodot%>/serialization/cpp-serialization/serialization-options.html">Data
Serialization Options</a>
</li>
<li class="has_submenu">
- <a
href="/docs/guide-native/<%=vars.product_version_nodot%>/serialization/data-serialization.html#pdx-serialization">Using
PDX Serialization</a>
+ <a
href="/docs/guide-native/<%=vars.product_version_nodot%>/serialization/cpp-serialization/using-pdxserialization.html">Using
PDX Serialization</a>
<ul>
<li>
<a
href="/docs/guide-native/<%=vars.product_version_nodot%>/serialization/cpp-serialization/pdxserializable-interface.html">Serialize
Using the PdxSerializable Class</a>
@@ -96,6 +96,11 @@ limitations under the License.
</li>
</ul>
</li>
+
+ <li>
+ <a
href="/docs/guide-native/<%=vars.product_version_nodot%>/serialization/cpp-serialization/pdxserializable-example.html">PdxSerializable
Example</a>
+ </li>
+
<li>
<a
href="/docs/guide-native/<%=vars.product_version_nodot%>/serialization/cpp-serialization/serialization-using-serializable.html">Serializing
Data with the DataSerializable Interface</a>
</li>
diff --git
a/docs/geode-native-docs/serialization/cpp-serialization/pdxserializable-example.html.md.erb
b/docs/geode-native-docs/serialization/cpp-serialization/pdxserializable-example.html.md.erb
new file mode 100644
index 0000000..780b138
--- /dev/null
+++
b/docs/geode-native-docs/serialization/cpp-serialization/pdxserializable-example.html.md.erb
@@ -0,0 +1,165 @@
+---
+title: PdxSerializable Example
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+DRAFT - Dave's notes interspersed.
+
+Why is this called "customserializable", rather than "PdxSerializable"?
+
+## Order.cpp:
+
+Front matter:
+
+ #include "Order.hpp"
+
+`PdxReader` & `PdxWriter` are used for `fromData()` & `toData()`:
+
+ #include <geode/PdxReader.hpp>
+ #include <geode/PdxWriter.hpp>
+
+ namespace customserializable {
+
+- Must provide `fromData()` and `toData()`.
+- Specify the keys in the same order in fromData and toData.
+- The order (no pun intended) in which the keys appear IS SIGNIFICANT in PDX
Serialization, though it probably
+shouldn't be since we're supposedly indexing by name, not by position in the
byte stream.
+
+ ```
+ void Order::fromData(PdxReader& pdxReader) {
+ order_id_ = static_cast<uint32_t>(pdxReader.readLong(ORDER_ID_KEY_));
+ name_ = pdxReader.readString(NAME_KEY_);
+ quantity_ = static_cast<uint16_t>(pdxReader.readInt(QUANTITY_KEY_));
+ }
+
+ void Order::toData(PdxWriter& pdxWriter) const {
+ pdxWriter.writeLong(ORDER_ID_KEY_, order_id_);
+ pdxWriter.markIdentityField(ORDER_ID_KEY_);
+
+ pdxWriter.writeString(NAME_KEY_, name_);
+ pdxWriter.markIdentityField(NAME_KEY_);
+
+ pdxWriter.writeInt(QUANTITY_KEY_, quantity_);
+ pdxWriter.markIdentityField(QUANTITY_KEY_);
+ }
+ ```
+
+Ivan says "toString is an override." What does he mean by that? Required by
interface spec, or what?
+
+ std::string Order::toString() const {
+ return "OrderID: " + std::to_string(order_id_) + " Product Name: " +
name_ +
+ " Quantity: " + std::to_string(quantity_);
+ }
+
+Do we need size?
+
+ size_t Order::objectSize() const {
+ auto objectSize = sizeof(Order);
+ objectSize += name_.capacity();
+ return objectSize;
+ }
+
+Do we need classname?
+
+ const std::string& Order::getClassName() const {
+ static const std::string CLASS_NAME = "com.example.Order";
+ return CLASS_NAME;
+ }
+
+Why `createDeserializable`?
+
+ std::shared_ptr<PdxSerializable> Order::createDeserializable() {
+ return std::make_shared<Order>(0, "", 0);
+ }
+
+ const std::string Order::ORDER_ID_KEY_ = "order_id";
+ const std::string Order::NAME_KEY_ = "name";
+ const std::string Order::QUANTITY_KEY_ = "quantity";
+
+ } // namespace customserializable
+
+## main.cpp
+
+Front matter. Any of these **required** for serialization (e.g. TypeRegistry)?
+
+ #include <iostream>
+ #include <sstream>
+
+ #include <geode/CacheFactory.hpp>
+ #include <geode/PoolManager.hpp>
+ #include <geode/RegionFactory.hpp>
+ #include <geode/RegionShortcut.hpp>
+ #include <geode/TypeRegistry.hpp>
+
+ #include "Order.hpp"
+
+Is `namespace apache::geode::client;` required for a client app?
+
+ using namespace apache::geode::client;
+ using namespace customserializable;
+
+Safe to assume that region & pool creation follow a template?
+
+ int main(int argc, char** argv) {
+ auto cacheFactory = CacheFactory();
+ cacheFactory.set("log-level", "none");
+ auto cache = cacheFactory.create();
+
+ auto poolFactory = cache.getPoolManager().createFactory();
+ poolFactory.addLocator("localhost", 10334);
+ auto pool = poolFactory.create("pool");
+
+ auto regionFactory = cache.createRegionFactory(RegionShortcut::PROXY);
+ auto region = regionFactory.setPoolName("pool").create("custom_orders");
+
+Again, why `createDeserializable`?
+
+ cache.getTypeRegistry().registerPdxType(Order::createDeserializable);
+
+Invoke the example code, report on progress...
+
+ std::cout << "Create orders" << std::endl;
+ auto order1 = std::make_shared<Order>(1, "product x", 23);
+ auto order2 = std::make_shared<Order>(2, "product y", 37);
+
+ std::cout << "Storing orders in the region" << std::endl;
+ region->put("Customer1", order1);
+ region->put("Customer2", order2);
+
+ std::cout << "Getting the orders from the region" << std::endl;
+
+ if (auto order1retrieved =
+ std::dynamic_pointer_cast<Order>(region->get("Customer1"))) {
+ std::cout << "OrderID: " << order1retrieved->getOrderId() << std::endl;
+ std::cout << "Product Name: " << order1retrieved->getName() <<
std::endl;
+ std::cout << "Quantity: " << order1retrieved->getQuantity() <<
std::endl;
+ } else {
+ std::cout << "Order 1 not found." << std::endl;
+ }
+
+ if (auto order2retrieved = region->get("Customer2")) {
+ std::cout << order2retrieved->toString() << std::endl;
+ } else {
+ std::cout << "Order 2 not found." << std::endl;
+ }
+
+Is `cache.close();` conventional or required?
+
+ cache.close();
+ }
diff --git
a/docs/geode-native-docs/serialization/data-serialization.html.md.erb
b/docs/geode-native-docs/serialization/cpp-serialization/using-pdxserialization.html.md.erb
similarity index 68%
copy from docs/geode-native-docs/serialization/data-serialization.html.md.erb
copy to
docs/geode-native-docs/serialization/cpp-serialization/using-pdxserialization.html.md.erb
index 3449af1..23a5cd9 100644
--- a/docs/geode-native-docs/serialization/data-serialization.html.md.erb
+++
b/docs/geode-native-docs/serialization/cpp-serialization/using-pdxserialization.html.md.erb
@@ -1,5 +1,5 @@
---
-title: Serializing Data
+title: Using PDX Serialization
---
<!--
@@ -19,19 +19,6 @@ See the License for the specific language governing
permissions and
limitations under the License.
-->
-Data in your client application's <%=vars.product_name%> cache must be
serializable to be shared with <%=vars.product_name%> servers and other
-<%=vars.product_name%> clients.
-<%=vars.product_name%> provides multiple data serialization options for
storage and transmittal
-between processes, of which **<%=vars.product_name%> Portable Data eXchange
(PDX) serialization** offers
-the best combination of versatility and ease-of-use for most applications.
-
-To learn more about other serialization options, see the subtopics in this
section describing serialization for the C++ and .NET APIs,
-[Data Serialization - C++](cpp-serialization/serialization-overview.html) and
-[Data Serialization -
.NET](dotnet-serialization/dotnet-data-serialization.html),
-and the [Data Serialization section in the _<%=vars.product_name_long%> User
Guide_](/serverman/developing/data_serialization/chapter_overview.html).
-
-# <a id="pdx-serialization" class="no-quick-link"></a>Using PDX Serialization
-
<%=vars.product_name%> Portable Data eXchange (PDX) serialization provides
portability for PDX serializable objects so that clients can share data with
Java servers and other non-C++ clients. PDX stores data in named fields that
you can access
individually in order to avoid the cost of deserializing the entire data
object. PDX also allows you
@@ -49,34 +36,34 @@ the `registerPdxSerializer` API.
You can also set the object preference of the cache to the `PdxInstance` type,
which allows you to access fields of a PDX object without deserializing the
entire object.
-- **[Serialize Using the PdxSerializable
Class](cpp-serialization/pdxserializable-interface.html)**
+- **[Serialize Using the PdxSerializable
Class](pdxserializable-interface.html)**
Domain classes need to inherit the `PdxSerializable` abstract class to
serialize and de-serialize the object. When you write objects using PDX
serialization, they are distributed to the server tier in PDX serialized form.
-- **[Performing put, get, and localDestroy Operations with a PDX Domain
Object](cpp-serialization/performing-ops-with-pdx-object.html)**
+- **[Performing put, get, and localDestroy Operations with a PDX Domain
Object](performing-ops-with-pdx-object.html)**
This topic demonstrates how you can perform operations on a PDX domain
object after you have implemented PDX serializable in your domain class.
-- **[Serialize Your Domain Objects with PdxSerializer and
PdxWrapper](cpp-serialization/using-pdxserializer.html)**
+- **[Serialize Your Domain Objects with PdxSerializer and
PdxWrapper](using-pdxserializer.html)**
For domain objects that you cannot or do not want to modify, use the
`PdxSerializer` and the `PdxWrapper` classes to serialize and deserialize the
object's fields.
-- **[Programming Your Application to Use
PdxInstances](cpp-serialization/using-pdxinstance.html)**
+- **[Programming Your Application to Use
PdxInstances](using-pdxinstance.html)**
A `PdxInstance` is a lightweight wrapper around the raw bytes of the PDX
serialized objects kept in the cache. It provides applications with run-time
access to files of a PDX serialized object. <%=vars.product_name%> provides the
implementation of the `PdxInstance` class.
-- **[Configuring PDX to Ignore Unread Fields During
Deserialization](cpp-serialization/pdx-ignore-unread-fields.html)**
+- **[Configuring PDX to Ignore Unread Fields During
Deserialization](pdx-ignore-unread-fields.html)**
Use the `setPdxIgnoreUnreadFields` API to control whether PDX ignores
fields that were unread during deserialization.
-- **[Using PdxInstanceFactory to Create
PdxInstances](cpp-serialization/using-pdxinstancefactory.html)**
+- **[Using PdxInstanceFactory to Create
PdxInstances](using-pdxinstancefactory.html)**
You can use the `PdxInstanceFactory` API to create a `PdxInstance` from
raw data when the domain class is not available on the server.
-- **[Using C++ Enum Type with PDX
Serialization](cpp-serialization/using-enum-type-with-pdx.html)**
+- **[Using C++ Enum Type with PDX
Serialization](using-enum-type-with-pdx.html)**
Because there is no "object" base type in C++, enums cannot be directly
passed as parameters to the `writeObject` and `readObject` API.
-- **[Using PDX Serialization with Delta
Propagation](cpp-serialization/pdx-with-delta-propagation.html)**
+- **[Using PDX Serialization with Delta
Propagation](pdx-with-delta-propagation.html)**
To use delta propagation with PDX serialization, you must implement the
`Delta` interface methods.
diff --git
a/docs/geode-native-docs/serialization/data-serialization.html.md.erb
b/docs/geode-native-docs/serialization/data-serialization.html.md.erb
index 3449af1..265d215 100644
--- a/docs/geode-native-docs/serialization/data-serialization.html.md.erb
+++ b/docs/geode-native-docs/serialization/data-serialization.html.md.erb
@@ -30,54 +30,3 @@ To learn more about other serialization options, see the
subtopics in this secti
[Data Serialization -
.NET](dotnet-serialization/dotnet-data-serialization.html),
and the [Data Serialization section in the _<%=vars.product_name_long%> User
Guide_](/serverman/developing/data_serialization/chapter_overview.html).
-# <a id="pdx-serialization" class="no-quick-link"></a>Using PDX Serialization
-
-<%=vars.product_name%> Portable Data eXchange (PDX) serialization provides
portability for PDX serializable objects so that clients can share data with
-Java servers and other non-C++ clients. PDX stores data in named fields that
you can access
-individually in order to avoid the cost of deserializing the entire data
object. PDX also allows you
-to mix versions of objects where you have added or removed fields.
-
-When using PDX serialization, you can use either `PdxSerializable` (for a
specific domain object) or `PdxSerializer` (for all your domain objects).
-
-**Use `PdxSerializable`** when the object is one whose definition you control.
You can embed the serialization/deserialization capability within
-the object, so its conversion from one format to the other is self-contained.
You do this by defining an object that inherits from the `PdxSerializable`
-interface, and you register the domain class using the
`registerPdxType(domainClass)` API.
-
-**Use `PdxSerializer`** when you cannot or do not wish to modify the object
definition, for example, when the object is provided by a third-party.
-You define the serialization/deserialization capability in a separate place,
then register the domain class for serialization in the cache using
-the `registerPdxSerializer` API.
-
-You can also set the object preference of the cache to the `PdxInstance` type,
which allows you to access fields of a PDX object without deserializing the
entire object.
-
-- **[Serialize Using the PdxSerializable
Class](cpp-serialization/pdxserializable-interface.html)**
-
- Domain classes need to inherit the `PdxSerializable` abstract class to
serialize and de-serialize the object. When you write objects using PDX
serialization, they are distributed to the server tier in PDX serialized form.
-
-- **[Performing put, get, and localDestroy Operations with a PDX Domain
Object](cpp-serialization/performing-ops-with-pdx-object.html)**
- This topic demonstrates how you can perform operations on a PDX domain
object after you have implemented PDX serializable in your domain class.
-
-- **[Serialize Your Domain Objects with PdxSerializer and
PdxWrapper](cpp-serialization/using-pdxserializer.html)**
-
- For domain objects that you cannot or do not want to modify, use the
`PdxSerializer` and the `PdxWrapper` classes to serialize and deserialize the
object's fields.
-
-- **[Programming Your Application to Use
PdxInstances](cpp-serialization/using-pdxinstance.html)**
-
- A `PdxInstance` is a lightweight wrapper around the raw bytes of the PDX
serialized objects kept in the cache. It provides applications with run-time
access to files of a PDX serialized object. <%=vars.product_name%> provides the
implementation of the `PdxInstance` class.
-
-- **[Configuring PDX to Ignore Unread Fields During
Deserialization](cpp-serialization/pdx-ignore-unread-fields.html)**
-
- Use the `setPdxIgnoreUnreadFields` API to control whether PDX ignores
fields that were unread during deserialization.
-
-- **[Using PdxInstanceFactory to Create
PdxInstances](cpp-serialization/using-pdxinstancefactory.html)**
-
- You can use the `PdxInstanceFactory` API to create a `PdxInstance` from
raw data when the domain class is not available on the server.
-
-- **[Using C++ Enum Type with PDX
Serialization](cpp-serialization/using-enum-type-with-pdx.html)**
-
- Because there is no "object" base type in C++, enums cannot be directly
passed as parameters to the `writeObject` and `readObject` API.
-
-- **[Using PDX Serialization with Delta
Propagation](cpp-serialization/pdx-with-delta-propagation.html)**
-
- To use delta propagation with PDX serialization, you must implement the
`Delta` interface methods.
-
-
