Portable versioning documentation #177
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Can one of the admins verify this patch? |
1 similar comment
|
Can one of the admins verify this patch? |
yagmurdulger
force-pushed
the
portable-versioning-documentation
branch
from
2c21641
to
5208e0a
Compare
This was referenced Jul 4, 2019
Closed
Closed
|
verify |
mdumandag
suggested changes
Jul 8, 2019
yagmurdulger
force-pushed
the
portable-versioning-documentation
branch
from
5208e0a
to
e504285
Compare
mdumandag
approved these changes
Jul 9, 2019
|
verify |
Serdaro
reviewed
Jul 9, 2019
README.md
Outdated
| @@ -766,7 +767,7 @@ As an alternative to the existing serialization methods, Hazelcast offers portab | |||
|
|
|||
| In order to support these features, a serialized `Portable` object contains meta information like the version and concrete location of the each field in the binary data. This way Hazelcast is able to navigate in the binary data and deserialize only the required field without actually deserializing the whole object which improves the query performance. | |||
|
|
|||
| With multiversion support, you can have two members where each of them having different versions of the same object, and Hazelcast will store both meta information and use the correct one to serialize and deserialize portable objects depending on the member. This is very helpful when you are doing a rolling upgrade without shutting down the cluster. | |||
| With multiversion support, you can have two members that each have different versions of the same object, and Hazelcast will store both meta information and use the correct one to serialize and deserialize portable objects depending on the member. This is very helpful when you are doing a rolling upgrade without shutting down the cluster. | |||
There was a problem hiding this comment.
With multiversion support, you can have two members each having different versions of the same object; Hazelcast stores both meta information and uses the correct one to serialize and deserialize portable objects depending on the member. This is very helpful when you are doing a rolling upgrade without shutting down the cluster.
README.md
Outdated
|
|
||
| Portable serialization supports versioning. It is a global versioning, meaning that all portable classes that are serialized through a member get the globally configured portable version. | ||
|
|
||
| You can declare Version in the configuration file `hazelcast.xml` using the `portable-version` element, as shown below. |
There was a problem hiding this comment.
You can declare the version in the hazelcast.xml configuration file using the ....
(I will improve this sentence also in the Hazelcast IMDG Reference Manual)
README.md
Outdated
|
|
||
| If you update the class by changing the type of one of the fields or by adding a new field, it is a good idea to upgrade the version of the class, rather than sticking to the global version specified in the `hazelcast.xml` file. | ||
|
|
||
| In Python Client, you can achieve this by simply adding the `get_class_version()` method to your class’s implementation of `Portable`, and setting the `CLASS_VERSION` to be different than the default global version. |
There was a problem hiding this comment.
In the Python client, you can ....
(Also, the two paragraphs above are connected, it is a good practice not to put a new line between them.)
README.md
Outdated
|
|
||
| In Python Client, you can achieve this by simply adding the `get_class_version()` method to your class’s implementation of `Portable`, and setting the `CLASS_VERSION` to be different than the default global version. | ||
|
|
||
| > Note: If your class that implements `Portable` doesn’t implement this method, its version is set by default to be the global version. |
There was a problem hiding this comment.
"> NOTE: If you do not use the get_class_version() method in your Portable implementation, it will have the global version, by default."
README.md
Outdated
|
|
||
| You should consider the following when you perform versioning: | ||
| * It is important to change the version whenever an update is performed in the serialized fields of a class, for example by incrementing the version. | ||
| * If a client performs a Portable deserialization on a field and then that Portable is updated by removing that field on the cluster side, this may lead to a problem. |
There was a problem hiding this comment.
I know this is the same content in the Hazelcast IMDG Reference Manual. However, for the sake of improving both documentation, could we give some examples:
"... , this may lead to problems such as ..."
yagmurdulger
force-pushed
the
portable-versioning-documentation
branch
from
25430be
to
2c4b9cd
Compare
Serdaro
reviewed
Jul 10, 2019
README.md
Outdated
| @@ -766,7 +767,7 @@ As an alternative to the existing serialization methods, Hazelcast offers portab | |||
|
|
|||
| In order to support these features, a serialized `Portable` object contains meta information like the version and concrete location of the each field in the binary data. This way Hazelcast is able to navigate in the binary data and deserialize only the required field without actually deserializing the whole object which improves the query performance. | |||
|
|
|||
| With multiversion support, you can have two members where each of them having different versions of the same object, and Hazelcast will store both meta information and use the correct one to serialize and deserialize portable objects depending on the member. This is very helpful when you are doing a rolling upgrade without shutting down the cluster. | |||
| With multiversion support, you can have two members each having different versions of the same object; Hazelcast stores both meta information and use the correct one to serialize and deserialize portable objects depending on the member. This is very helpful when you are doing a rolling upgrade without shutting down the cluster. | |||
There was a problem hiding this comment.
... information and uses the ...
README.md
Outdated
| If you update the class by changing the type of one of the fields or by adding a new field, it is a good idea to upgrade the version of the class, rather than sticking to the global version specified in the `hazelcast.xml` file. | ||
| In the Python client, you can achieve this by simply adding the `get_class_version()` method to your class’s implementation of `Portable`, and setting the `CLASS_VERSION` to be different than the default global version. | ||
|
|
||
| > Note: If you do not use the `get_class_version()` method in your `Portable` implementation, it will have the global version, by default. |
There was a problem hiding this comment.
Let's stick with the standard "Note" admonition:
"> **NOTE: ........ **"
Serdaro
approved these changes
Jul 12, 2019
|
verify |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds documentation for multiversion support of Portable Serialization in README inspired by the Reference Manual (with necessary changes for Python). It also improves the format of the headings and subheadings under Portable Serialization. It includes a versioning example for the Foo class as well.