Modeling Basics

A goal of the platform is to make working with messages and state as simple as working with plain old java objects. The X Platform's Application Data Modeler (ADM) allows modeling of messages and state entities in XML and provides utilities to generate source code that is instrumented to transparently handle encoding, serialization and transactional functionality that underpin the platform. This section will familiarize you with theses modeling constructs and code generation tools.The ADM model allows the definition of three types of complex or composite types: Entities, Embedded Entities, and Messages. These will be discussed in more detail below. Here is a high-level definition of the three.

• Entity
  • Entities are used to model application state. In Talon, an application exposes its state to the platform by providing it with a single root object that references the rest of the application state. The single root and its descendent object entities form a state tree that is held fully in memory, supports transactional semantics, and is replicated asynchronously to backup instances in a delta-based pipelined fashion as application code modifies it in the course of processing. 
• Message
  • A message can be thought of as a special type of entity that is enhanced to allow transport over the platform's Simple Message Abstract (SMA) layer. A message can't reference other entities because it is serialized as an independently transportable unit. 
• Embedded Entity
  • An embedded entity models a collection of fields of primitive types or other embedded entities. An embedded entity can be embedded into a Message, Embedded entities are serialized along with the parent Message or Entity that it is added to. Because embedded entities can be set on message types they are useful when it comes to transferring related groups of fields between messages and state.

As a convenience, there is also:

• Inlined Entity
  • An embedded entity can be "inlined" into another type such that it inherits the embedded entity's fields.  

 An application's state is formed by a collection of entities held entirely in memory and is rooted by a single node. 

 Messages are independently serializable units made up of primitive and embedded entities. 

ADM Types

Primitive/Built-In Types:

The X Platform supports the following built-in types which can be used as fields when building composite entity types:

Collections and Arrays

The following built-in collection types are supported. 

Restrictions on Collections

• Array types are limited to primitive, built-in, and embedded entity types. They are intended to allow embedded values that are transported along with a message or entity, and consequently:
• Queue and Map types can only be used with non-embedded entities and may only use other non-embedded entities as their values.

Enumerations

The X Platform supports modeling of enumeration types. Enumeration types can be of type int, char or string and, according to their type, they must be assigned a code value that is used to generate their field tag for protobuf/xbuf encoding:

• For integer coded enums, the value is the same as the (integer) code, 
• For character coded enums, the value is the ASCII value of the (character) code, and
• For string coded enums, the value is the hash code of the (string) code.

Entities

Composite data types are defined as entities which can contain fields that are primitive, built-in, collection, enumerations, entity or message types. Because Messages are a special case of Entities we start by describing Entities here first.

An application's state is exposed to the platform via a single root object that along with its descendant entity references form your application's state tree in which each entity is an independently serializable node. The platform replicates the deltas to this state tree as changes are made to its entities. When an entity is set as a field of another entity in the tree it constitutes an addition to the state tree which is then replicated to other peers. Similarly as fields on an entity are updated, the changed node is replicated to backup members, and finally, when an entity is dereferenced from the tree a remove operation is replicated. 

An entity that serves as the root of a state tree can be marked as root, which indicates it will not have any parents in the object tree. A root object should not be declared as the child of another Application provided state should not be defined as root objects because the AepEngine appends them to an underlying root object internally. 

An entity type can be marked as transactional. The platform tracks field updates to transactional entities and can rollback changes made to them in the event of an application exception or an explicit rollback. By default, entities and collections are transactional while messages are not. A message can be declared transactional, which is useful in the event that a message is stored as part of an application's state tree. 

See State Tree Limitations for some important limitations on the current state tree implementation that may have an impact on state modeling.  

Embedded Entities

An entity can be declared as embedded. Embedded entities are serialized as part of the entity/message to which it is declared as a field - as part of the same transported unit. Embedded entities can define fields that are primitive or built-in types, other embedded entities, or arrays, but may not use collections or non-embedded entities. 

Restrictions on the use of entities as fields in other objects

• Entities declared as embedded cannot be defined such that there are cycles in the resultant tree.
• Entities declared as embedded cannot currently be used as members in collections, but may be used as array members. 

Messages

Messages can be thought of as a special type of entity that additionally implements and exposes a MessageView interface allowing them to be transported via the platform's Messaging layer. Because messages must be transportable as a single serialized unit, messages can only declare fields that are primitive, built-in, embedded entities or arrays of the previous; non embedded entities and collections aren't supported.

Messages can be used independently from the Messaging Engine and Message Store.

• Messages can be used with the platform's SMA (Simple Message Abstraction) layer using its MessageBus and MessageChannel abstractions. See: http://build.neeveresearch.com/core/javadoc/LATEST/com/neeve/sma/package-summary.html
• Or messages can be used truly independently via external frameworks by utilizing their byte[] or ByteBuffer serializers and/or their generated factory methods. To assist in determining type/factory information the platform provides a MessageMetadata class that can be transported along with the message for type resolution.

Using the XML Model

The X Platform generates source code for entities and messages for use with the runtime from an XML model specified by the x-adml.xsd schema included at the root of the nvx-adm-<version>.jar and also bundled into the nvx-all.jar. Be sure to update your editor's schema validator to reference it.

Model Element

The root element of a message model is the model element, which is used to define a namespace qualified set of modeling elements. To conform to x-adml.xsd schema and pass validation, a model must define target XML namespace xmlns="http://www.neeveresearch.com/schema/x-adml". This is not to be confused with the namespace attribute described below.

Naming the Model

ADM model has a name property which is used in certain ways during code generation.

Two main uses of a model name are:

• Name of .proto file when IDL is generated.
• Name of outer java class that wraps model types when code is generated with Protobuf encoding.

Model name can be derived from the filename, or by defining it explicitly in XML. Name explicitly defined in XML takes precedence over filename.

For the example above, name property will have a value of ModelNameGoesHere (it will be converted to Pascal Notation). If we do not define name attribute, the model name would be derived from filename: sampleModel.xml -> SampleModel.

Documentation and Javadoc

Most model elements can be documented by supplying a child <documentation> element or doc attributes. The documentation added to the model is used to generate Javadoc in the generated source code.

XML

Generated Code

Model Element Deprecation

Types in an ADM Model can be marked as deprecated via a deprecation attribute. Such elements are generated with deprecation annotations and Javadoc. Adding a child deprecation element optionally allows providing a 'since' attribute and brief message describing the reason for deprecation. 

XML

Generated Code

All methods related to a deprecated field are marked as deprecated. The code snippet below shows some examples of this. 

Imports

The import statement allows you to import messages entities and fields from a model in a different namespace. 

The code generator needs to be able to resolve imported models to correctly generate source code. This is accomplished using an import statement that specifies the imported model location:

See also Imported Model Resolution

Factories

The factories section defines object factories that are used to instantiate the generated object. Each factory in an application must have a unique factory id. The ID is serialized along with the object or transported in MessageMetadata and is used to reconstitute its objects during deserialization. A single model can define multiple factories, allowing Messages and Entities to be grouped together as the application sees fit. A factory can contain a maximum of 32767 types, so in practice, it is rarely a requirement to use multiple factories within a single model. Each type in the model defines the factory to which it belongs via its factoryid attribute. The user application may define factories with ids greater than or equal to 1, ids <= 0 are reserved for platform internal use. 

Enumerations

Enumeration types can be modeled as follows and can be declared as fields of entity or message types. Unlike other model elements, enumerations aren't tied to a particular factory despite being scoped to the model's namespace. Generated java enumerations don't have dependencies on the rest of the platform and can be used standalone. 

XML

Generated Enumerations can specify a type which is accessible in the generated code. The type can be int, char or String. A const should not be removed from an enumeration, if the newly generated code is expected to deserialize enums that were persisted with an earlier version, in addition, the order of constants is important and should not be changed.

Generated Source

For an entity named "MyEntity" an interface and an implementation are generated using the model's namespace. Entities will extend IRogNode or IRogContainerNode marking so that they can be used as nodes with the platform's Replicated Object Graph (ROG) framework. 

Fields and Accessors

The ADM model allows fields either to be defined in place (directly on the message or entity that is using the field) or by reference to a field declared in the model's <fields> section. It is a matter of preference which approach an application developer uses: if many messages contain the same field, then it may be more convenient to model the fields in a reusable fashion in the <fields> element, but in most cases, it is more convenient to define the fields in place. 

XML

Field Attributes

Field Reference Attributes

<fieldRef> element can override most attributes in the referenced field:

Attribute	Description	Required
ref	The name of the referenced field. Name may be with or without the namespace of owner model (i.e. full-qualified name). In both cases, the field will be looked up in both the current model and its imports. If the non-fully-qualified name is declared in the current model and in one of the imports, the field from the current model will take precedence. If multiple imports define the same name, an error will be reported. The best practice when importing a field from another model is to use the fully qualified name of the imported field (e.g. com.example.importedmodel.someField), as this insulates your model from future conflicts in the event that imported models are changed.
name	Optionally, a name for the field that overrides the referenced field's name. Otherwise, the field name defaults to that of the referenced field.
jsonName	Optionally overrides the referenced field's jsonName.
id	Optionally overrides the id specified by the field being referenced. Field ids must be between 0 and 32767 inclusive
required	Whether or not the field is a required field for the type. Fields declared as required will cause a check to be added for the value being set in the generated types isValid() method.
pinned	Indicates whether or not the field is pinned. A pinned field always occupies the same space on the wire.
isKey	True if this field should serve as the key when inserting the entity into a LongMap or StringMap collection. In this case, insertion of the message in the collection with a given key will update this field with the key value.
doc	The doc to use for the field which overrides that specified by the referenced field.
deprecated	When true all methods generated for the field will be marked as deprecated.

Generated Field Accessors

Standard Setters/Getters

All field types will produce a regular getXXX and setXXX for the field along with clearXXX and hasXXX methods.

Latency sensitive applications should note that assigning a returned primitive value to an object wrapped primitive type (e.g. Integer int = message.getMyIntField()) will result in an object allocation. 

Zero Garbage Setters/Getters

For UUID and XString types, additional zero garbage accessors to the underlying raw type which is backed by the message buffer are additionally generated (though only zero garbage when used in conjunction with Xbuf with pooling enabled). For these types, some additional accessors are also generated to allow copying the value into and out of the message in an efficient zero garbage fashion:

Standard Accessors

The standard accessors are not guaranteed to be zero garbage and are less efficient because the require encoding of the type into its underlying byte representation. 

Copying Accessors

The setXXXFrom / getXXXTo accessors allow zero garbage copying of the field value when Xbuf encoding is used for the message. These copying operations are zero garbage and can be very efficient because the copy operation can be done directly using the preserialized bytes for the type.

Unsafe Accessor

The unsafe accessor allows the user to get a direct reference to the field with no copy; the returned type directly references the underlying raw bytes in the serialized message. This accessor is useful in cases where the caller will itself copy the value into an outbound message using a copying setter, or where the caller will use the source type purely within the handler of the message from which it takes the reference. The caller is not permitted to retain the object beyond the source object's lifespan and may not in any way modify the returned type.  

This operation can be dangerous in the presence of object pooling because, if the application erroneously retains a reference to the type, its value will be invalidated when the message is returned to its pool and its backing buffer will be wiped or repurposed. Applications that use this API should operate with special care and should avoid using this accessor unless performance is of the utmost concern. 

List Accessors for array types

When Xbuf encoding is used for an array type and pooling is enabled, the underlying implementation doesn't store the field value in an array because pooling varying array sizes is impractical. To achieve zero garbage for fields modeled as arrays, a List interface is more appropriate, and a XIndexedList is returned. A XIndexedList implements java.util.List, but also provides reusable iterators. These accessors are discussed in detail in the section Zero Garbage Array Accessors.

Date field accessors

For zero garbage access on date fields, it is possible to use the 'AsTimestamp' accessors to access the field as the number of milliseconds since the epoch. 

Embedded Entity Accessors

To avoid garbage for embedded messages entities when using Xbuf encoding, while still providing a mechanism for applications to hold such fields in state beyond the lifespan of the message from whence they came, additional take/lend accessors are generated for embedded entity fields. Considerations for using embedded entity fields in the context of message pooling are discussed in detail in the section Embedded Entities.

Unset Fields Getters

When a field has not been set on a type, the following table indicates what the getXXX() accessor will return:

Type	Unset Field Return Value	hasXXX	Notes
Java Primitive	The default value for java primitive type		For numeric values 0, for boolean false, for char ''.
String, Date,	null
Enum	null
Entity	null
Array	Empty Array		Depends on code gen configuration property generateArrayGetterEmptyIfNull

For java primitive types, the hasXXX() method can be called to distinguish whether the value was explicitly set or is just returning the default value.

For arrays, it is not possible to distinguish between an empty array or the array not being set. This allows ADM code to operate with Protobuf encoding under the covers, which is not able to distinguish between an empty or unset array. For this reason, ADM generated code does not generate a hasXXX method for arrays. Setting the code generation property generateArrayGetterEmptyIfNull controls whether an empty or null array is returned when there are no values encoded in the underlying message or entity. 

Default Getters

The ADM Model supports the ability to generate 'default getters' which accept a default value to return when the field being accessed is not set. This can be enabled by passing the generateDefaultGetters=true directive to the AdmCodeGenerator. Default getter accessors will be created for any field type that has a corresponding hasXXX getter to accept a default value to return when the field is not set. While supported, usage of this setting is not recommended: the preferred mechanism is for applications to call hasXXX() directly instead. 

XML

Generated Code

Semantic Types

The ADM model provides a <types> section that can be used to define types based on the platform's primitive and built-in types. Such semantic types can be used in place of their corresponding primitive type in the model and will inherit their documentation. The type used for the field in generated messages and entities will be the base type specified by the named field.

XML

Generated Code

Note that "Price" doesn't result in a new java type being created. The generated source uses its base type (float) directly and inherits the documentation of the semantic type. This is true of all semantic types, with the exception of types with a base of String that are declared as poolable (See poolable string types below).

Poolable String Types

The X Platform provides an XString implementation that allows zero garbage manipulation of Strings. Low latency applications should use XStrings instead of Java Strings in domain state  This allows for zero garbage copy of fields to and from outbound and inbound messages and zero garbage manipulation of fields by domain logic. Although the use of XStrings will eliminate garbage, it will not eliminate object promotion across heap generations which can be an expensive operation. To avoid promotions, low latency applications also need the ability to pool and pre-allocate such fields. To make working with such types easier, the ADM model provides support for creating subtypes of XString that are poolable. For String fields that are declared as poolable, the ADM code generator will generate code implementing a new type for the field that is a subtype of XString and the associated classes that allow for the pooling and pre-allocation of fields of this type. All of the methods currently available on XStrings will be available to the subtype. The XString documentation can be found at: http://build.neeveresearch.com/core/javadoc/LATEST/com/neeve/lang/XString.html

Zero garbage applications typically operate with poolable string fields in one of two fashions:

• Creating a corresponding pooled string factory that is configured for preallocation, and using that to source strings stored in state at runtime that are initialized by copying a value out of a message. It is important that string fields that are held in application state are copied out of the message because if the message itself is pooled, the value of the string will be reset after the message handler returns. 

• Creating a working variable to temporarily hold a mutable pooled string value.

  Note that this pattern doesn't actually leverage the pooling capabilities of the MyPooledString type, as it retains the reference.

Declaring a String field to be poolable

A poolable type will be created for a String field if:

• The field or type element that defines it has a poolable="true" attribute. The String type will be created based on the name of the field. 
• A semantic type is defined with a base type of string and the poolable attribute set to true. The String type will be based on the name of the type. 
• For applications that would rather separate the notion of pooling from the model itself, the Code Generator can be run with a directive indicating that all String fields should generate a poolable type (see Directives in the sections below).
• In the future, different narrower directives may be introduced for finer-grained control over what String fields will create poolable types.

Restrictions:

• A poolable string type cannot be created such that it conflicts with a built-in or primitive type name (string, integer, Currency, etc), nor can the poolable type conflict with a type name used elsewhere within the model (enumerations, entities, messages or collections). In the case where a field name conflicts with one of these types, a semantic type with a different name should be declared to avoid the naming conflict.

Pooled String Type Name Conflicts

As stated above, a poolable string type's name may not clash with built-in platform types, other types declared in the model or types in java.lang. For pooled string types that are generated from a field name (rather than a semantic type definition), the ADM code generator supports two optional directives that can make such collisions less likely: pooledStringFieldTypeNameSuffixPolicy, which specifies the policy for resolving conflicts detected by the code generator, and pooledStringFieldTypeNameSuffix to allow the developer to specify a suffix that should be applied to generated pooled types (defaults to 'String' if not specified). 

• None: (Default) With this policy, field names are not suffixed, and it will result in either a code generation or compilation error if a conflict occurs. This policy is useful where the model developer wants to proactively monitor for such conflicts, and perhaps declare the pooled string field as a semantic type in the <types> section to resolve the conflict.  
  
• Always: With this policy, the pooled string type is always suffixed with String, which greatly reduces the likely hood of a name conflict. 

• OnConflict: With this policy, the code generator will suffix the generated pooled string type name with 'String' when the name conflicts with another type. For example:

  would yield a pooled string type of MyEnumString to avoid conflicting with the MyEnum enumeration type.

XML

Note that for pooled strings, if the length parameter is not specified, the backing buffer size for preallocated Strings will default to 32 bytes. If a length is specified, then that size will be used for the default backing buffer size value for preallocating Strings of that type.

Generated Code

From the standpoint of a message or entity, a pooled string field is treated no differently than a normal String field. The field's setters accept an XString and the getters return an XString. The field value in the message is not itself pooled, rather the value is pooled along with the message. In other words, a pooled string type allows pooling of strings in application code, not message code. The code generator will generate a subclass of XString with an inner class factory type that can be used for preallocating XStrings for use by the application:

Notes

• The application can create factories for the generated types to allow application preallocation of the pooled type. 
• The generated factory returns uninitialized XStrings with the option of creating immutable (constant) instances. 
• A newly created object will start with an ownership count of 1. The ownership count is used to track an object’s reference count. Users can acquire a pooled object to prevent it from being disposed and cleared. Calling dispose on the type will return it to the pool when the ownership count reaches 0. If the objects returned by the pool will be acquired/disposed across multiple threads, the factory should be created as threaded. 

Preallocation of Pooled Strings

Strings from inbound message fields are often stored in domain state. To that end, poolable string types need to be preallocated along with the rest of application to avoid creating new instances at runtime. There are two approaches to handling preallocation:

1. Preallocate the pooled string type with preallocated application state, and copy the string from the inbound message into domain state. In this approach, the message keeps its reference to the pooled string field and reuses the same reference when the message is recycled through its pool. 
2. Use take/lend semantics in the same fashion as with a Nested Entity as described in Embedded Entities. The domain state needn't preallocate the pooled string type but rather takes if from the message which then draws a new instance from a globally configured preallocated when the message itself is recycled to its pool.  

Configuring Preallocation and the Pooled Type's Default Factory

Using the static creation methods on a generated pooled type will draw a new instance from the generated type's default factory. The default factory is created in the pooled types static initializer block. Therefore, any configuration of the default factory needs to be done before the class is loaded for the values to take effect. Generated Messages draw their values from the default pool. Because messages are themselves pooled, it is not necessarily required that the factory's pool use preallocation to avoid allocating new pooled types at runtime if the application preallocates the strings and copies values out of the message. 

The following properties may be set for each pooled type:

So, in our example above to enable pooling for a ComplianceId and to preallocate 10,000 instances, the following code should be executed before any code makes a reference to ComplianceId:

Creating New Factory Instances

If the application will handle allocating Strings used in application state up front and will copy values from messages into application state, then the application should create a separate Factory that preallocates the expected number of types. This can be done with the Factory's newFactory(...) method:

Depending on the application, it is possible that the Factory need not be threaded if only one thread will be creating Strings from this factory and will never dispose of the strings it creates. If this is the case, then there is no risk that another thread will return the string to the pool and introduce concurrency issues.  

Creating New Factory Instances Generically

It is also possible to create pooled types in a more generic fashion, as illustrated below. This approach can be more convenient in cases where application code dynamically pre-allocates objects at runtime. 

Entities

Entities are defined in the entities element of the model and must have a unique id with respect to other types within the scope of their factory.

XML

Entity Attributes

Attribute	Description	Required
name	The name of the field, must be unique within the model.
id	The id of the entity, which must be unique within the scope of all types in the entity's factory. Entity / Message ids must be between 0 and 32767 inclusive
factoryId	The id of the factory, which must be unique within the scope of all factories used within an application. When a message is received, the factoryId and entityId uniquely identify the type to be deserialized. factory IDs <= 0 are reserved for platform use.
asEmbedded	Defaults to false, Indicates whether or not this entity is generated to be used as an embedded or child field of another entity. Embedded entities are always serialized transported with its parent entity. Entities used as fields in messages must be declared as embedded.
transactional	Whether or not this entity supports transaction commit and rollback via the applications ODS store.

Entity Field Attributes

Attribute	Description	Required
type	The type of the element. If the type is defined in this namespace, is defined in only one of the imported models, or is a primitive or collection type, only the simple name of the type need be used. A non-fully-qualified name will be looked up in both the current model and its imports. If name is declared in the current model and in one of the imports, the type from the current model will take precedence. If multiple imports define the same name, an error will be reported. The best correction in such case is to use the fully-qualified name. If the field is an array type, it should be suffixed with array indices such as MyEntity[] to denote it as an array.
name	The name of the field, must be unique within the model.
jsonName	Contains the name of the JSON property that will be used for the field when the message is serialized to JSON. Defaults to using the value defined in name.
id	The id of the field. The id must be unique with the scope of this entity. For Xbuf/Protobuf encoding, this tag is used as the tag value for the field on the wire. If not set, a unique id will be generated by the source code generator. For better control over compatibility, it is recommended that application set this value manually. Field ids must be between 0 and 32767 inclusive
length	If this field refers to a variable length type (such as string), this indicates the maximum length of the field.
pinned	A pinned field always occupies the same space on the wire.
isKey	True if this field should serve as the key when inserting the entity into a LongMap or StringMap collection. In this case, insertion of the message in the collection with a given key will update this field with the key value.

Generated Source

For an entity named "MyEntity" an interface and an implementation will be generated using the model's namespace. Entities will extend IRogNode or IRogContainerNode marking that they can be used as nodes with the platform's Replicated Object Graph (ROG) framework. 

Messages

Messages are defined in the messages element and must have a unique id with respect to other types within the scope of their factory. Messages can use all modeling capabilities of entities, but cannot use non-embedded entities or non-array collections as fields.

XML

Message Attributes

Messages support the same attributes as entities (listed above) with the exception that transactional defaults to false for messages. 

Message Field Attributes

Message fields support the same attributes as entities (listed above).

Notes

For Xbuf and Protobuf encoding, the id is used to generate the protobuf field tag, so changing field ids will break wire compatibility. If fields are not explicitly assigned IDs in the model, then the ADM generate will assign them automatically. in this case, fields should not be removed or changed in order to maintain wire compatibility with earlier versions of the generated code. 

Messages can only declare primitive types, built-in types, embedded types as fields (or arrays of those types). Collections, Messages, and non-embedded Entities can't be used.

Generated Source

For an entity named "MyMessage" an interface and an implementation will be generated using the model's namespace. Entities will extend IRogNode or IRogMessage, marking that they can be used as nodes with the platform's Replicated Object Graph (ROG) framework and the platform's Simple Message Abstraction (SMA) Layer.

Collections

Collections are defined in the <collections> element and must also have a unique id with respect to other types within the scope of their factory. Collections may not be declared as embedded at this time. 

XML

Generated Source

Inlined Entities

The fields from an embedded entity can be 'inlined' into another message or entity. Inlining an embedded entity produces the same result as if all of the fields for the given entity were defined on the entity itself. It is not possible to inline the fields of a Message or a non embedded entity at this time.

A type that inlines another type will generate code that implements the inlined types's generated interface. 

XML

Restrictions

• An embedded entity cannot be inlined into another embedded entity in a manner that will produce inlining cycles.
• An embedded entity cannot inline a Message or Entity.
• Messages and non-embedded entities cannot be inlined.
• A Message can't inline 2 embedded entities that have conflicting field definitions (e.g. fields with the same name but with attributes that differ in any way other than their doc or required attributes). In the case of required, if an embedded entity defines a field as required, then it will be required on the message.
• The isKey and pinned field attributes on an embedded entity are ignored when the entity is inlined into another message or entity. 
• A Message can't define fields that conflict with any of its inlined embedded entities (e.g. fields with the same name but with attributes that differ in any way other than their doc or required attributes). 
  Exceptions to this rule are:
  • required: In the case of the required attribute, the value set on a message field wins (a particular message can override the required field attribute on an inlined embedded entity).
  • isKeyField: entity or message inlining the embedded entity can set the isKey attribute for a given inlined field. 
  • pinned: the pinned attribute can be overridden by the inlining entity. 

Generated Source

Note that Javadoc is omitted below and only the simple accessors are listed for brevity.

Required Field Validation

A required field can be declared by setting its required attribute. The required attribute is optional and defaults to false. When required fields are defined, checks for their presence will be added to the type's isValid() method. Calling getValidationErrors() on a type missing that field will result in an error of the form: "myDoubleField is not set" being added to the provided list. Neither the Messaging Engine nor the transport layer will invoke isValid() on a given message, validation checks are left to the application code. 

To generate logic for required fields, the generateRequiredFieldValidators=true directive should be passed to the AdmCodeGenerator.

XML

Generated Code

Model Evolution and Compatibility

Because Message and Entities are serialized and deserialized, it is important that modeled objects can evolve over time without breaking the ability to deserialize objects from a previous evolution of a model. For example, if the type of a message field is changed from one release of your application to the next, a receiver that is still on an older version that receives the message won't be able to deserialize the message. To ensure that such issues don't occur, follow the set of guidelines and rules outlined below. Similarly, if your application is configured to persist to a transaction log and you later try to read from the transaction log with the newly generated code, it won't be able to read from the older serialization. 

1. Don't change the ids of factories. 
2. Don't change the ids of types. 
   1. If a type will no longer be used, it is better to deprecate it to avoid accidentally declaring a new type the reuses the old type id later. 
3. Declare the id attribute on fields. 
   1. If you don't declare field ids, ADM will assign them in the order they are declared, but this means that any reordering or removal of the field would result in different type ids. 
4. Don't remove fields on messages.
   1. It is better to deprecate a field rather than remove it. This avoids the potential for accidentally reusing the field id. 
5. Don't change the type of a field. If a field type needs to be changed, deprecate the existing field and add a new field with the same type. 
   1. It is generally okay to change a scalar type such as a byte to a short, int or long, or a float to a double, but not vice-versa.
6. Don't change the name of fields.
   1. For JSON encodings, changing the field name is a breaking change.
   2. For Xbuf and Protobuf encodings, it is technically okay to change the name of the field as long as the id remains the same. 

Following the above steps will allow applications generated with the new versions of the model to still interoperate.

There are a few additional compatibility issues to consider if the generated code will be shared between multiple projects. These are covered in Runtime Compatibility.

Next Steps

Once you have modeled your messages and state, you'll need to decide on what message encoding to generate and generate the state. The following sections cover these topics. 

• Generating Source Code - Discusses how to integrate code generation into your project's build. 
• Choosing an Encoding - Discusses the differences between the various encoding types supported by ADM. 
• Runtime Compatibility - Discusses implications on runtime compatibility when using code generated with a different platform version. 

And once you have generated your messages and state, the following sections walk through how to work those objects when writing an application. 

• Working with Messaging
• Working with State Replication
  
• Working with Event Sourcing