Dynamic Attributes API

Model

Dynamic attributes implement the Entity-Attribute-Value model.

Diagram

  • Category defines a category of objects and the corresponding set of dynamic attributes. The category must be assigned to some entity type.

    For example, there is an entity of the Car type. We can define two categories for it: Truck and Passenger. The Truck category will contain Load capacity and Body type attributes, and the Passenger category – Number of seats and Child seat.

  • CategoryAttribute defines a dynamic attribute related to some category. Each attribute describes a single field of a definite type. The required code field contains the system name of the attribute. The name field contains the human-readable attribute name.

  • CategoryAttributeValue – dynamic attribute value for a particular entity instance. Dynamic attribute values are physically stored in the dedicated SYS_ATTR_VALUE table. Each table record has a reference to some entity – ENTITY_ID column.

An entity instance can have dynamic attributes of all categories related to the entity type. So if you create two categories of the Car entity mentioned above, you will be able to specify any dynamic attribute from both categories for a Car instance.

If you want to have an ability to classify an entity instance as belonging to a single category, for example, a car can be either truck or passenger, the entity must implement Categorized interface. In this case, an entity instance will have the reference to a category, and dynamic attributes from this category only.

Loading and Saving

Loading and saving dynamic attribute values is handled by DataManager. Use one of these methods to indicate that dynamic attributes should be loaded for entity instances:

  • setHint(DynAttrQueryHints.LOAD_DYN_ATTR, true) method of LoadContext.

  • hint(DynAttrQueryHints.LOAD_DYN_ATTR, true) method of the fluent API.

By default, dynamic attributes are not loaded. At the same time, DataManager always saves dynamic attributes contained in entity instances passed to save().

Dynamic attribute values are available through getValue() / setValue() methods of EntityValues. Pass the attribute code with the + prefix to these methods, for example:

@Autowired
private DataManager dataManager;

public void increaseLoadCapacity(Car car, int value) {
    Car carLoad = dataManager.load(Car.class)
            .id(car.getId())
            .hint(DynAttrQueryHints.LOAD_DYN_ATTR, true)
            .one();
    Double capacity = EntityValues.getValue(car, "+TruckLoadcapacity");
    EntityValues.setValue(car, "+TruckLoadcapacity", capacity + value);
    dataManager.save(car);
}

In fact, you rarely need direct access to attribute values in the application code. Any dynamic attribute can be automatically displayed in any Table or Form component bound to a data container with the entity for which the dynamic attribute was created. You can specify attribute visibility in screens and components while configuring dynamic attributes.