mirror of
https://github.com/OpenHFT/Chronicle-Map.git
synced 2021-09-13 01:26:12 +00:00
Initial re-work of documentation
This commit is contained in:
Executable
+77
@@ -0,0 +1,77 @@
|
||||
= Chronicle Map 3 Compatibility
|
||||
Neil Clifford
|
||||
:toc: macro
|
||||
:toclevels: 1
|
||||
:css-signature: demo
|
||||
:toc-placement: macro
|
||||
:icons: font
|
||||
|
||||
toc::[]
|
||||
|
||||
== Java Implementation Compatibility
|
||||
|
||||
=== Public API
|
||||
|
||||
For Chronicle Map, the *public API* is comprised of public classes that are included in [Javadoc](
|
||||
http://www.javadoc.io/doc/net.openhft/chronicle-map/).
|
||||
|
||||
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>>
|
||||
Reference in New Issue
Block a user