In This Section

Overview

Code generation is accomplished using the ADMGenerator class distributed with the ADM module (nvx-adm-<vesion>.jar or the nvx-talon-all-<version>.jar). The xml schema is bundled in these jars at the jar root: /x-adml.xsd.

Encoding Types

ADM code generation currently supports generating classes in the following encoding types :

Json: Javascript Object Notation serialization; not very efficient but highly readable
Protobuf: Google's protobuf serialization format, which can be useful for portability purposes providing a reasonable balance between performance and interoperability.
Xbuf: Neeve's protobuf implementation which can operate in a wire compatible mode with Google's protobuf, but allows zero garbage operation along with other performance enhancements.

Protobuf IDL

For Xbuf and Protobof the protobuf idl (.proto) is output in the generated source folder using the model's fully name space.

Generated Encoding Output

Invoking the code generator on a model outputs source for objects in a particular encoding: Json, Xbuf or Protobuf to a package that is by default defined as the model's name space. The code generator however can be used to generate source to a namespace specified to the code generator. This makes it possible to generate source for mulitple encodings of the same model by invoking the code generator multiple times with a separate namespace and encoding for each execution. Furthermore it is possible to convert between any of the separate encodings by serializing/deserializing to json which is compatible between all encodings (and in the case of Xbuf/Protobuf to a binary format since the are binary compatible).

It is perfectly legal to mix separate encoding types at runtime across different models so long as the models have separate factory ids (since the factory id is used to determine which generated factory to use to decode a message).

While it is legal to mix and match different encoding types within your application, it is isn't possible to mix and match encodings within a model via import. For example, if you generate one model with protobuf, it is not possible to use types already generated with protobuf in a model being generated with Xbuf.

Directives

Some advanced properties can be passed to the code generator as directives. The following is a list of supported directives:

Directive	Description	Default
generateEmbeddedEntityInterfaces	Directive indicating that the generator should create interfaces for embedded entities. This can be disabled for applications with stringent performance requirements to reduce the overhead associated with multi-morphic vtable lookups.	true
generateDefaultGetters	Whether or not to generate default getters that accept a value to return when the field is not set. Not typically recommended	false
generateThrowOnUnsetGetters	Whether or not to generate getXXXOrThrow() or accessors that will throw an ERogFieldNotSetException when the field has not been set. This provides an alternate to calling hasXXX for a field to test if the field is unset. Usage of this directive is not recommended; hasXXX is the recommended approach to testing if a field is not set. Exception throwing is more expensive, and the generated getXXXOrThrow method introduces extra invocation overhead and a larger code size.	false
generateRequiredFieldValidators	Whether or not validation logic is generated in the types validators for required fields. Enabling this leads large generated code size, and validation checks are expensive, so this is not recommended for performance sensitive applications.	false
generateFluentSetters	Directive indicating that fluent style setters should be generated for fields. This can be enabled to generate fluent accessors on generated types. This can be useful for writing concise testcode, but is more overhead, so it's usage is not typically recommended.	false
generateAllStringsPoolable	Directive indicating that all Strings fields in the model should be generated as poolable types regardless of the value of the field's poolable attribute.	false
pooledStringFieldTypeNameSuffixPolicy	Can specify None, Always or OnConflict to instruct the code generator as to how to handle naming conflicts that arise from a pooled string field type name generated from a field name are suffixed to avoid a name clash.	"None"
pooledStringFieldTypeNameSuffix	Specifies the suffic to use to resolve pooled string type name conflicts with Always or OnConflict suffixing policies.	"String"

Running with java

To run the generator with java you can use:

java –cp nvx-adm-<version>.jar[:jars-containing-imports] com.neeve.tools.AdmCodeGenerator /
-e Xbuf –f <model-file>.xml -o target/generated-sources/nvx-adm

or you can use the platform jar which contains adm:

java –cp nvx-platform-<version>.jar[:jars-containing-imports] com.neeve.tools.AdmCodeGenerator / 
-e Xbuf –f <model-file>.xml -o target/generated-sources/nvx-adm -d generateEmbeddedEntityInterfaces=false

Using Maven

To use the code generator with Maven add the following to your pom's plugin section:

Maven Plugin Goals	Description
generate, adm-generate	Generates code to a generated sources folder which would be included in the built jar.
generateTest, adm-generateTest	Generates code to a generated test sources folder which would be included in the built test jar

<plugins>
  <plugin>
    <groupId>com.neeve</groupId>
	<artifactId>nvx-core-maven-plugin</artifactId>
    <version>${nvx.core.version}</version>
	<executions>
	  <execution>
        <id>Minimal-Messages-Xbuf</id>
        <phase>generate-sources</phase>
        <goals>
        <goal>generate</goal>
        </goals>
        <configuration>
          <modelFile>${basedir}/src/main/java/com/acme/messages/messages.xml</modelFile>
          <encodingType>Xbuf</encodingType>
		  <directives>
			<generateEmbeddedEntityInterfaces>false</generateEmbeddedEntityInterfaces>
		  <directives>
        </configuration>
      </execution>
     </executions>
   </plugin>
</plugins>

Using the Platform Plugin

If your project is using the nvx-platform-bom and you want to generate code with the same version of the platform you are using, you may also use the nvx-platform-maven-plugin. The advantage of this approach is that you can use the same version of the plugin as the platform bom. Because maven BOMs don't cover plugin versions, using the nvx-core-maven-plugin would mean that the nvx-core-maven-plugin-version would have to be specified separately.

<plugins>
  <plugin>
    <groupId>com.neeve</groupId>
	<artifactId>nvx-platform-maven-plugin</artifactId>
    <version>${nvx.platform.version}</version>
  </plugin>
</plugins

Using ANT

<target name="gen-model-sources">
	<java classname="com.neeve.tools.AdmCodeGenerator" 
          fork="true" 
          failonerror="true" 
          jvm="${build.java.home}/bin/java" 
          classpathref="build.classpath">
		<arg value="-e"/>
		<arg value="Xbuf"/>
		<arg value="-f"/>
		<arg value="${basedir}/src/main/java/com/acme/messages/messages.xml"/>
		<arg value="-o"/>
		<arg value="-o target/generated-sources/nvx-adm"/>
		<arg value="-d generateEmbeddedEntityInterfaces=false"/>
	</java>
</target>

Imported Model Resolution

To handle multi module and multi project builds, the ADM XML Parser, and Maven Build plugin search for model imports on the classpath using the imported model's fully qualified namespace. The model xml (and .proto for Xbuf/Protobuf) will be copied to the generated source folder in fully qualified form. To allow other models to resolve the model being generated from their classpath, users should ensure that these files are copied to the target classes folder.

ADM Code Generator Maven plugin will copy these files by default to target classes folder, and include them into project artifact's jar.

Import resolution searches both current classpath and OS file system when resolving an import. Recommended is to use relative classpath strings whenever possible. Consider the following example project with two models, model.xml imports other_model.xml:

${basedir}/src/some/package/model.xml [In xml we define namespace = "some.model.namespace"]
${basedir}/src/other/package/other_model.xml [In xml we define namespace = "some.other_model.namespace"]

The recommended way to define import would be one of the following:

<!-- 
Method #1: (recommended) Import from relative model namespace. 
Imports from classpath relative to namespace of importing model, 
in this case some.model.namespace. 
This would try resolving from 
some/model/namespace/../../other_model/namespace/other_model.xml. 
Evaluating ../.. would give us resource some/other_model/namespace/other_model.xml
-->
<import model="../../other_model/namespace/other_model.xml" />
 
 
<!-- Method #2 (recommended): Import from full model namespace. 
This will work if generated sources are compiled and added to classpath. 
For example if we have project dependencies where one project imports a 
model XML from another project, the original XML file is not available, 
but the one in the produced jar is. Therefore, we are getting file from 
classpath, where project dependency containing import is added to the classpath. 
For maven this also works within the same project if code generation for imported 
other_model.xml is run first. So, when we reach in pom the code generation of model.xml, 
other_model.xml is already generated and xml is copied to 
target/classes/some/other_model/namespace/other_model.xml. 
target/classes is already in classpath so this will resolve successfully to other_model.xml-->
<import model="some/other_model/namespace/other_model.xml" />

Reason why this works is because result of running code generation would be:

${basedir}/target/classes/some/model/namespace/model.xml
${basedir}/target/classes/some/model/namespace/Model.proto
${basedir}/target/classes/some/model/namespace/GeneratedModelClass1.class
${basedir}/target/classes/some/model/namespace/GeneratedModelClass2.class
...

${basedir}/target/classes/some/other_model/namespace/other_model.xml
${basedir}/target/classes/some/other_model/namespace/OtherModel.proto
${basedir}/target/classes/some/other_model/namespace/GeneratedOtherModelClass1.class
${basedir}/target/classes/some/other_model/namespace/GeneratedOtherModelClass2.class
...

The requirement is that code generation first runs for other_model.xml so that it can be found in classes folder at the time of running model.xml.

The following modes of import model resolution are provided for advanced use cases but are discouraged.

<!-- Method #3: Import from absolute filesystem path: -->
<import model="absolute path to file other_model.xml in the OS filesystem" />

<!-- Method #4: 
Import as path relative to the provided modelsDir provided to the code generator
${modelsDir}/other/package/other_model.xml.
-->
<import model="other/package/other_model.xml" />
<!-- Method #5: 
Import as relative filesystem path. Path is relative to 
model that does the import so this is evaluated to 
${basedir}/src/some/package/../other/package/other_model.xml. 
If we evaluate ../ we get ${basedir}/src/some/other/package/other_model.xml
-->
<import model="../other/package/other_model.xml" />

Platform Bundled IDLs

The platform bundles the following IDLs in the packaged jars to support custom options used by ADM to enrich handling of enums, and to define additional data types used by ADM.

IDL	Full Path	Description
descriptor.proto	google\protobuf\descriptor.proto	Defines options available in Protobuf
AdmTypes.proto	com\neeve\adm\types\protobuf\AdmTypes.proto	Defines custom enum options and additional ADM data types

Regeneration of Imported Models

(coming soon)

The ADM Code generator will be enhanced to allow the code generator to operate in a mode in which it will regenerate all pre-built imported models. This intent of this mode is that it will ensure that all models used by an application are built with the same version of the platform that the importing application is built with. This can be used to work around issues where older dependencies haven't been updated to a newer version of the X platform which is no longer API compatible.

Incremental Smart Code Regeneration

The Maven Plugin and ADM Code generator take a source model's last modified timestamp or checksum into account. Code generation will be skipped if:

Model file has been changed since last build.
Any import model file has changed (checked recursively in imports of imports...)
Any input option for code generation has changed such as encoding type, namespace, directives etc.

The incremental code generation works by tracking above given changes in an xml file which may be found in output dir. The file has name with pattern like this:

.${model_filename}.xml_${md5checksum}.metadata. model_name is name of model file for which code was generated. md5checksum is a signature calculated from input options given to code generator, so that if any of them changes, the resulting filename no longer represents same code generation. Stored in this file are input options given to code generator and list of models with a number that would be different every time model file is persisted to disk. These files do not go into jar, and may be deleted at any time (which they usually do when clean build is triggered).