Property definitions

Property definitions

In TG, properties are fundamental atoms that form entities. Similar to attributes in conceptual modeling, properties describe characteristics of entity types and their relationships to other entity types. And similar to columns in a database schema, properties can be decorated with meta-data that describes their integrity constraints.

In Java terms -- a property is any field declared by an entity type and annotated with @IsProperty. Similarly, the integrity constraints are also described using annotations.

Classification

All properties are classified according to the following essential criteria:

1. Nature

• Persistent - backed by a data storage, which they can be saved to and retrieved from.

• Transient - not backed by a data storage.

  Typically used in synthetic and action entities but also applicable to persisent entities. Transient properties can also optionally belong to one of the following classes:

  • Calculated - read-only value is derived by computing the associated expression.
  • Crit-only - used to provide additional search criteria, hence application is limited to EQL expressions.

2. Type

• Entity - entity types.
• Collectional - represent a collection of values.
• Primitive - types with a single component (e.g., String).
• Composite - types with multiple components. For example, type Money might have 2 components:
  • amount : BigDecimal
  • currency : Currency

Additionally, a property may admit a combination of the following characteristics:

1. Requiredness

   Property must be assigned a value. After assignment, the value cannot be removed, only replaced.

2. KeyMembership

   Property constitutes a part of its entity's key. Implies Requiredness.

3. OptionalKeyMembership

   Requires KeyMembership, excludes Requiredness.

4. Finality

   The first value that a property is persisted with remains unchanged for the whole lifetime of an entity.

5. ...

Property types

The following property types are supported by the platform:

1. Primitive
   • Standard Java: [Long, Integer, BigDecimal, Date, String, boolean, Class, Currency, byte[]].
   • Platform: [Colour, Hyperlink].
2. Composite: [Money].
3. Domain Entity: any registered domain entity (at the time of writing, this means an entity, registered in an application specific class ApplicationDomain).
4. Value Entity: Union Entity, PropertyDescriptor.
5. Collectional types: any type assignable to java.util.Collection and parameterised with a type listed in items 1-3 (boxing of primitive types applies). Additionally, any type assignable to Map.
6. DynamicEntityKey which is applicable only to property key.
7. NoKey which is applicable only to property key.

Collectional properties

Apart from the set of supported collection element types, the following rules apply to definitions of collectional properties:

1. The field must be declared using the final modifier.

Accessors (getters) and setters

Entity definition must include a pair of accessor and setter methods for every declared property.

Accessors

Accessor is synonymous with getter and serves the same purpose. The naming convention permits 2 kinds of prefixes immediately followed by the capitalised name of the property:

1. is -- intended to be used with boolean properties
2. get -- intended to be used with all other types of properties

In most cases an accessor method should simply return the property's value as-is. However, for collectional properties an unmodifiable view should be returned to facilitate immutability. The standard Collections class provides a rich variety of methods for this purpose.

Setters

Setter (also called mutator) is a method of a single argument that updates the respective property's value. The only naming convention uses prefix set followed by the capitalised name of the property.

A setter method must be declared with public or protected visibility.

It is recommended to match the return type of a setter with the type of its declaring entity type, in order to benefit from method chaining. This can be achieved by ending a setter's body with return this.

All setter methods must be annotated with @Observable in order to enable interception.

In most cases a setter method should update its property's value in a straight-forward manner -- by means of assignment. However, for collectional properties (which are final) it is required to first clear the collection and then add all elements of the argument.

@Observable
public Vehicle setParts(final List<Part> parts) {
    this.parts.clear();
    this.parts.addAll(parts);
    return this;
}