In This Section
Compatibility Matrix
Below lists the changes for ADM generated code compatibility. See Adm Compatibility Level documentation for an explanation on ADM generated code compatibility.
ADM Maven | ADM Compat | Notes |
|---|---|---|
3.0.503 -> 3.1.103 | 2.4.0 | First 3.0 release |
3.1.104 -> 3.2.120 | 3.0.0 | Enhancements for detecting incompatible enums required new apis in generated code |
3.2.121 -> 3.4.67 | 3.1.0 | Adding support for Field Interest registration for Xbuf |
| 3.4.373 -> 3.5.126 | 3.4.0 | Support for Message copy Generated Code can run with 3.4.373 to 3.X |
| 3.5.127 -> 3.6.X | 3.4.1 | Support for pass-through field preserving entity copy and Message.copyXXXTo(Entity) Generated Code can run with 3.4.373 to 3.X
|
| 3.7.162 -> 3.7.216 | 3.7.0 | Changed protobuf message copy() to preserve pass-through fields, changed getXXXTo implementation to use copyInto() for embedded fields. Changed Xbuf generated entities to use XbufHeuristics class to source deync policy and sparse optimization flags ... requires new platform APIs. Generated Code can run with 3.7.162 to 3.X |
| 3.7.217 -> 3.8.63 | 3.8.0 | Changed Xbuf embedded entity array accessors to allow for reduce memory usage. The changes to the generated code require new platform APIs Generated Code can run with 3.7.217 to 3.X |
| 3.8.64 -> 3.8.108 | 3.8.1 | Changed the ADM generated lendXXX(XString val) method to allow it to accept a null value without throwing a NullPointerException See XPLATFORM-1823 Generated Code can run with 3.7.217 to 3.X |
| 3.8.126 - 3.8.158 | 3.8.2 | Fixes a compiler warning in XBuf generated code relating the deprecated PktBuffer.create method. See XPLATFORM-1886 Generated Code can run with 3.7.217 to 3.X |
| 3.8.159 -> 3.8.187 | 3.9.0 | Changes the code generated by ADM for collection nodes by moving more of the implementation code into the platform collection base classes. See XPLATFORM-1903 Generated Code can run with 3.8.159 to 3.X |
| 3.8.188 -> 3.8.193 | 3.9.1 | Optimizing Xbuf generated messages' <T> getXXXTo(XString.Factory<T> factory) methods for better performance with FrameFields. See XPLATFORM-1915 Generated Code can run with 3.8.159 to 3.X |
| 3.8.194 ->3.11.0 | 3.9.2 | New code generator option to generate embedded entities as non final. This change does not other wise change the generated apis. See XPLATFORM-1445 Generated Code can run with 3.8.159 to 3.X |
| 3.11.55 -> 3.12.x | 3.10.0 | New State Replication Map types and ERogFieldNotWriteable exceptions require new runtime APIs. See XPLATFORM-2080 Generated Code can run with 3.11.55 to 3.X |
| 3.14.19 | 4.0.0 | Changed the data type fields ids of generated classes from int to long See XPLATFORM-2228 Generated Code can run with 3.14.19 to 3.X |
| 3.16.15 | 4.1.0 | Added support to track and report memory utilization statistics. The changes to the generated code require new platform APIs See RUMI-107 Generated Code can run with 3.16.14 to 3.X |
These were introduced 3.5.127, 3.6.84 patch releases ... prior 3.5 and 3.6 versions wereAPI Compatibilty Goals
Wire Compatibility
Wire compatibility refers to the ability to be able to deserialize messages and entities off the wire or from disk.
- Within a major version of X, wire compatibility is maintained unless there are extraordinary circumstances. So regardless of API compatibility level in the generated code, it should always be possible to deserialize messages that were generated and serialized with the same major version.
- Note, however, that wire compatibility is contingent on the application model remaining compatible (e.g. fields not removed and field ids not changed).
API Compatibility
API compatibility refers to the compatiblity between code generated by one version of the platform, and its compatiblity at runtime with another version.
- A best effort is made to maintain backwards API compatibility with code generated within the same major version so that a new version of the platform runtime can operate with code generated within that version.
- However:
- To allow introducing new functionality in the generated code, sometimes dependencies on new platform APIs are introduced. In this case, a minor API compatibility version is incremented. This means that newly generated code can not be used with older versions of the platform.
- In extreme cases, such as critical bug fixes, it is possible that API changes are required in the generated code API which necessitate a major increment, which in turn makes a newer version of the platform require newly generated code (older generated code cannot be used).
Versioning Recommendations
This section provides recommendations on how to version your projects to ensure that they can use the latest and greatest ADM generated source code for their models.
Small Projects
For small projects that are not versioned independently, regenerating ADM models with each release is the best way to ensure that your generated models are API compatible with the runtime.
Large Projects
For larger organizations that have applications that are versioned independently and upgrade X Platform version in a staggered fashion, it can be a challenge if those applications share the same models while on different X versions. There are 2 strategies for handling this situation:
Strategy 1 - Each Project Builds Private Models
If you have relatively few models, having each project generate and build its own private copy of the generated ADM source code is a simple approach to ensure that each project can use ADM code generated with their target platform version. It can break down if your organization has a lot of shared models, and then Strategy 2 may be more appropriate.
Strategy 2 - Centrally build platform qualified Models
In this approach, ADM models that are shared by multiple projects are built and managed as independently versioned artifacts. The generated ADM source code is generated against each platform version to be used by the organization as a whole. The resulting artifact is qualified with the X Platform version so that the resulting artifact reflects both the model version and the platform version from which it was generated.
For example, take an ADM Model called common-messages share by Project A and Project B that are both initially using X Platform 3.1.104, but will be independently upgrading to X 3.2.121.
common-messages v1.0
And then the model is changed to add a new long field:
common-messages v1.1
Under this scheme, the common-messages would be built and packages as:
- common-messages-1.0-adm3.1.104.jar
- common-messages-1.1-adm3.1.104.jar
- common-messages-1.0-adm3.2.121.jar
- common-messages-1.1-adm3.2.121.jar
The above packaging allows each project to independently upgrade to either the model version or a compatible X version as appropriate. If Project B upgrades to platform version 3.2.121 it could do the following:
- continue to use common-messages-1.0-adm3.1.104.jar:
- It won't get the new long field in v1.1 model. When it receives a 'MyMessage' serialized by the v1.1, version myLongField will be invisible.
- It won't get the enhancement for detecting stale enums in the 3.2.121 generated code.
- switch to common-messages-1.1-adm3.1.104.jar:
- If will pick up the new long field in v1.1. It can exchange 'MyMessage' with Project A, but Project A won't see the value of myLongField until it upgrades to a 1.1 version of the model.
- It will not get the platform enhancements in the generated code.
- switch to common-messages-1.0-adm3.2.121.jar: If Project B isn't ready for v1.1 of the model, but want the platform enhancements in generated code.
- It won't get the new long field in v1.1 model. When it receives a 'MyMessage' serialized by the v1.1 version, myLongField will be invisible.
- It will get platform enhancements in the generated code.
- switch to common-messages-1.1-adm3.2.121.jar:
- If will pick up the new long field in v1.1. It can exchange 'MyMessage' with Project A, but Project A won't see the value of myLongField until it upgrades to a 1.1 version of the model.
- It will get platform enhancements in the generated code.
- If will pick up the new long field in v1.1. It can exchange 'MyMessage' with Project A, but Project A won't see the value of myLongField until it upgrades to a 1.1 version of the model.