Dynamic Attributes API

Model

Dynamic attributes implement the Entity-Attribute-Value model.

Category specifies a category of objects and the corresponding set of dynamic attributes. Each category needs to be linked to a specific entity type.

For instance, consider an entity classified as Car. In this scenario, we can create two categories: Truck and Passenger. The Truck category may encompass attributes like Load capacity and Body type, while the Passenger could include attributes such as Number of seats and Child seat.
CategoryAttribute represents a dynamic attribute associated with a specific category. Each attribute defines a single field with a specific data type. The required code field holds the system identifier of the attribute, while the name field contains the human-readable attribute name.
CategoryAttributeValue signifies the value of a dynamic attribute for a specific entity instance. These values are stored in the dedicated SYS_ATTR_VALUE table. Each record in the table is linked to a particular entity through the ENTITY_ID column.

An entity instance can possess dynamic attributes from all categories linked to its entity type. For instance, if you establish two categories for the Car entity as described earlier, you can assign any dynamic attribute from both categories to a Car instance.

If you want to categorize an entity instance under a single category - for instance, a car being classified as either a truck or passenger - the entity must implement the Categorized interface. This setup ensures that an entity instance is affiliated with a specific category and possesses dynamic attributes exclusively from that category.

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;

@ViewComponent
private DataGrid<Car> carsDataGrid;

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

In practice, direct access to attribute values in the application code is seldom necessary. Any dynamic attribute can be automatically displayed in any DataGrid or FormLayout component linked to a data container featuring the entity associated with the dynamic attribute. When setting up dynamic attributes, you can define attribute visibility within views and components.