...
| div | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||
|
...
- 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).
...
- 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 necessitates necessitate a major increment, which in turn makes a newer version of the platform require newly generated code (older generated code cannot be used).
...
For small projects that are not versioned independently then , regenerating ADM models with each release is the best way to ensure that your generated models are API compatible with the runtime.
...
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 approaches to strategies for handling this situation:
Strategy 1 - Each Project Builds Private Models
If you have relatively few models, simply 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 Stategy then Strategy 2 below 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 and the . 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.
Take for 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.
...
| Code Block | ||
|---|---|---|
| ||
<model namespace="com.example" defaultFactoryId="1">
<messages>
<message name="MyMessage" factoryid="1" id="1">
<field name="myIntField" type="Integer"/>
<field name="myLongField" type="Long"/>
</messsage>
</messages>
</model> |
Under this scheme, the common-messages would be built and packages as:
...