Compatibility

Overview

As new functionality is added to the platform and new features are added to the generated source code, source code generated by ADM changes as well. There are several facets to generated ADM source that have compatibility impacts to consider:

• ADM generated source depends on platform APIs that may not exist in earlier versions.

• ADM generated source depends on imported class that are potentially generated with an earlier version of ADM.

• ADM objects are serialized between different versions of the platform, so there are wire format considerations.

• The application's ADM model evolves over time (new types and fields may be added or removed).

This sections discusses how the compatibility is enforced.

Compatibility Policy

The following are rules of compatibility for the various types of compatibilities that Talon maintains across release versions.

In general, every effort will be made to maintain compatibility between release versions for all types of compatibility (API, Binary and Generated Code). The rules below indicate when compatibility can be broken in the event there is deemed a need to break compatibility.

Binary Compatibility

Binary compatibility refers to the ability to be able to deserialize messages and entities off the wire or from disk across different X Platform versions.

Policy

Wire compatibility is maintained within a major version (unless there are extraordinary circumstances).

Wire compatibility can be broken across major versions.

Wire compatibility is contingent on the application model adhering to the ADM model compatibility rules. This topic is discussed in Modeling Message and State

API Compatibility

API compatibility refers to the ability of applications built using a particular version of the platform to be compiled, without error, on another version of the platform i.e. whether a code change is needed when migrating the application between platform versions.

Policy

API compatibility is maintained within a major version.

API compatibility can be broken across major versions.

Generated Code Compatibility

Generated code compatibility refers to the compatibility between code generated by one version of the platform, and its compatibility at runtime with another version.

Policy

A best effort is made to maintain backwards generated code 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. This means that newly generated code can not be used with older versions of the platform. In this case the minor version ADM Compatibility Version of the generated code is incremented.

• In other cases, although rare such as critical bug fixes, it is possible that changes in the platform make older versions of the generated code incompatible with the newly released platform version. This means that the code has to be regenerated to work with the new version of the platform runtime. In this case, the major version ADM Compatibility Version of the generated code is incremented.

ADM Compatibility Version

An ADM Compatibility Version is a version number, in the form of [MAJOR].[MINOR].[PATCH], that is maintained by the platform runtime to validate compatibility between code generated by the ADM code generator and the platform runtime. Each class generated by the ADM is annotated with the AdmGenerated. This annotation contains a field, named compatLevel , that contains the ADM Compatibility Version of with the platform runtime (which includes the ADM code generator) used to produce the generated code. The compatLevel field in this annotation is used to determine if the generated code is compatible with the platform runtime against which it is being run.

When a message/state factory is registered with the platform, it examines the compatLevel in the generated code with the current ADM Compatibility Version i.e, the ADM Compatibility Version associated with the platform runtime with which the message/state factory was registered. An exception is thrown in case the generated code is not compatible with the platform runtime. See Compatibility Check Logic for more details on how the platform performs this comparison.

The ADM Compatibility Version is versioned and tracked independently of the platform version. Each release of the platform is accompanied by its ADM Compatibility Version. This version is the value that is placed in the compatLevel field of the code generated by the ADM code generator in the released version of the platform. A summary of ADM Compatibility Versions with what caused the change in the version is maintained in the ADM Compatibility Matrix.

AdmGenerated Annotation

To validate compatibility of the generated code with the version of the platform jars on which the generated classes are being used, a com.neeve.adm.runtime.annotations.ADMGenerated annotation is added to classes generated by the ADM code generator. This annotation has runtime retention and is thus available for introspection by applications at runtime. The following is an example of such an annotation

@Generated(value="com.neeve.adm.AdmFactory", date="Mon May 04 01:49:14 PDT 2015")
@AdmGenerated(
        encoding = "Protobuf",
        compatLevel = "2.0.0",
        admVersion = "nvx-core-all v1.9-SNAPSHOT (build 0)",
        date = "5/4/15 1:49 AM",
        buildInfo = "Common Dictionaries 1.0")
final public class CommonDictionaryFactory implements IStoreObjectFactory, MessageViewFactory {
...
}

AdmGenerated Properties

Property	Description
encoding	For types generated with a particular encoding, this will be set to the encoding used.
admVersion	Set to the version of the platform binary that was used to generate the code.
date	The date and time at which the code was generated
buildInfo	This can be supplied to the ADM code generator at build time allowing the user to insert information about their build version. This can be done by supplying -b on the ADM code generator command line. When using the Maven plugin, the configuration property can be used to provide custom buildInfo other than default - (tool) format

Debugging Compatibility Errors

Trace can be enabled to display the version of the platform that generated the factory when it is registered with the runtime to assist with support issues. For message factories, set nv.sma.trace=verbose and nv.ods.trace=verbose for state factories. Sample output from this trace is:

com.neeve.toa.sample.oms.dict.OmsDictionaryFactory(id=-23) ADM generated (encoding=Protobuf, compatLevel=2.0.0, buildDate=5/4/15 1:49 AM, admVersion=nvx-core-all v1.9-SNAPSHOT (build 0), buildInfo=nvx-toa-sample-dict-1.0-SNAPSHOT (nvx-core-maven-plugin))

It is also possible for the application to call the following to collect the above trace

• MessageViewFactoryRegistry.dumpFactoryVersionInfo(StringBuilder)

OR

• StoreObjectFactoryRegistry.dumpFactoryVersionInfo(StringBuilder)

Disabling Compatibility Checks

Though not recommended, it is possible to disable compatibility checks by setting the nv.adm.disablecompatcheck configuration property to true. This can be done via a system property, system environment variable or as a DDL environment variable.

Compatibility Check Logic

At runtime, when message and/or state factories are registered with the platform, the platform validates whether the generated classes are compatible with the platform runtime. It does so using the logic described below. If not compatible, the platform throws an EAdmCompatibilityException exception.

Bump In Patch Version

A bump in the patch version of the ADM Compatibility Version may be used by a newer version to indicate that the generated code supports additional APIs or capabilities. For the same major and minor versions, two differing patch versions are always forward and backward compatible. For example, code generated by the platform with an ADM Compatibility Version of 2.0.0 is compatible with any platform runtime with ADM Compatibility Version of 2.0.x where x >= 0. Additionally, Any code generated with a platform with ADM Compatibility Version of 2.0.x where x >= 0 is compatible with the 2.0.0 platform runtime.

Bump In Minor Version

A bump in minor version indicates that newly generated code is not compatible with previous versions of the platform runtime. For example, code generated by the platform runtime with ADM Compatibility Version of 2.1.0 is not compatible with the 2.0.0 platform runtime. However, the code generated with platform runtime with ADM Compatibility Version of 2.0.0 continues to be compatible with the 2.1.0 platform runtime.

Sample Compatibility Error

Caused by: com.neeve.adm.runtime.EAdmCompatibilityException: com.neeve.aep.messages.AepMessageFactory 
generated with ADM 'nvx-adm v1.10.300 (build 300)' and a compatibility level of '2.1.0' is not compatible with 
platform version 'nvx-core-all v1.9.275 (build 275)' with a compatibility level of '2.0.0'
    at com.neeve.adm.runtime.AdmCompatibility.assertRuntimeCompatibility(AdmCompatibility.java:125)
    at com.neeve.sma.MessageViewFactoryRegistry.registerMessageViewFactory(MessageViewFactoryRegistry.java:218)
    at com.neeve.aep.AepEngine.<clinit>(AepEngine.java:3138)
    ... 10 more

Bump In Major Version

A bump in major version means that code generated by the platform runtime is not backwards or forwards compatible with the platform runtime. In other words, the released platform runtime cannot operate with code generated with an older major version and an older version of the platform runtime can't operate with a newer version of generated code. For example, a platform runtime with ADM Compatibility Version of 3.0.0 is not compatible with code generated by the platform runtime with ADM Compatibility Version of 2.6.7 and the code generated by the platform with ADM Compatibility Version of 3.0.0 is not compatible with the platform runtime with ADM Compatibility Version of 2.x.y for any value of x and y.

A Sample Compatibility Error

Caused by: com.neeve.adm.runtime.EAdmCompatibilityException: com.neeve.aep.messages.AepMessageFactory 
generated with ADM 'nvx-adm v1.9.275 (build 275)' and a compatibility level of '2.0.0' is not compatible with 
platform version 'nvx-core-all v2.0.100 (build 100)' with a compatibility level of '3.0.0'
    at com.neeve.adm.runtime.AdmCompatibility.assertRuntimeCompatibility(AdmCompatibility.java:125)
    at com.neeve.sma.MessageViewFactoryRegistry.registerMessageViewFactory(MessageViewFactoryRegistry.java:218)
    at com.neeve.aep.AepEngine.<clinit>(AepEngine.java:3138)
    ... 10 more