Skip to content

Latest commit

 

History

History
63 lines (48 loc) · 3.4 KB

compatibility.md

File metadata and controls

63 lines (48 loc) · 3.4 KB

Chronicle Map 3 Compatibility

The Java Implementation Compatibility

Public API

For Chronicle Map, public API is comprised of public classes that are included in Javadoc. Other public classes are not subject for the following rules, they might be changed in any way, or 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, 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 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 shouldn't communicate to each other. Though this might lead to failures, but not to data corruption on either of the nodes.

The 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 provided by the specification shouldn't be weaken.