API 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.

<model namespace="com.example" defaultFactoryId="1">
  <messages>  
    <message name="MyMessage" factoryid="1" id="1">
        <field name="myIntField" type="Integer" doc="A sample integer field"/>
    </messsage>
  </messages>
</model>

And then the model is changed to add a new long field:

<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:

• 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.