mirror of
https://github.com/OpenHFT/Chronicle-Map.git
synced 2021-09-13 01:26:12 +00:00
78 lines
3.5 KiB
Plaintext
Executable File
78 lines
3.5 KiB
Plaintext
Executable File
= Chronicle Map Compatibility
|
|
Neil Clifford
|
|
:toc: macro
|
|
:toclevels: 1
|
|
:css-signature: demo
|
|
:toc-placement: macro
|
|
:icons: font
|
|
|
|
toc::[]
|
|
|
|
== Java Implementation Compatibility
|
|
|
|
=== Public API
|
|
|
|
The *public API* comprises public classes that are included in
|
|
http://www.javadoc.io/doc/net.openhft/chronicle-map/[Javadoc].
|
|
|
|
Note: Other public classes are not subject to
|
|
the following rules; they may be changed in any way, or even removed.
|
|
|
|
- Class and method names, types and number of parameters in already existing methods shouldn't be
|
|
changed.
|
|
- Any methods could be added to the classes and interfaces that are not subject for
|
|
subclassing or implementing by the library users, such as `ChronicleMap`, `ChronicleMapBuilder`,
|
|
`MapEntry`, but in a way that any existing code calling methods on those classes still compile, not
|
|
break due to ambiguity in method resolution.
|
|
- Only non-abstract (concrete or default) methods could be added to the classes and interfaces that
|
|
are subject for subclassing by the library users, such as `MapMethods`, `MapEntryOperations`,
|
|
`SizedReader`.
|
|
|
|
=== Behaviour
|
|
|
|
Semantics and actual effects of API calls might change between Chronicle Map versions with
|
|
[different `<minor>` number](versioning.md), e. g. default serialization forms of key or value objects
|
|
of some types could change, "high level" configurations in `ChronicleMapBuilder` could produce
|
|
Chronicle Maps with different "low level" configurations, etc. Such changes should be documented in the release notes.
|
|
|
|
=== Persistence File Binary Form
|
|
|
|
A persisted Chronicle Map store (a binary file), produced by a production release of the library,
|
|
should be accessible and updatable by any subsequent production release of the library in 3.x
|
|
branch, unless the older version has bugs that lead to data corruption.
|
|
|
|
To support this:
|
|
|
|
- Serialization forms of any classes shouldn't be changed. When e. g. a marshaller class (say,
|
|
`StringBytesReader`) of objects of some type is changed, and it's serialization form should be
|
|
changed, a new class called `StringBytesReader_3_5` (5 is the `<minor>` number of the version of the
|
|
library, in which this change is made) should be created and put along with older class.
|
|
|
|
- When the specification revision is updated (hence binary form could be completely changed), a
|
|
new version of root implementation class, e. g. `VanillaChronicleMap_3_5` should be created and
|
|
put along with older version, which should keep behave the same as before.
|
|
|
|
=== Replication Protocol
|
|
|
|
The replication protocol might change between Chronicle Map versions with different `<minor>` number.
|
|
Chronicle Map nodes running different versions of the library should not communicate to each other.
|
|
This may lead to failures, but not to data corruption on either of the nodes.
|
|
|
|
== Specification Compatibility
|
|
|
|
The Chronicle Map Data Store Specification could be updated without changing the revision while it
|
|
remains backward compatible, i. e. the implementation of the newer version of the specification
|
|
could access and update any persisted Chronicle Map store, produced by an older version.
|
|
In addition, potential *concurrent* accessing implementations of older versions ("within" the same
|
|
revision) shouldn't lose correctness and corrupt the data.
|
|
|
|
If more substantial changes to the specification are required, the revision number should be
|
|
updated.
|
|
|
|
The binary form of Chronicle Map and algorithms could change between revisions to any degree, but
|
|
[guarantees](../spec/1-design-goals.md#guarantees) provided by the specification shouldn't be
|
|
weaken.
|
|
|
|
'''
|
|
<<../ReadMe.adoc#,Back to ReadMe>>
|