An Enum can be used in all those scenarios where it is useful to have constant information directly on the engine model, such as a list of states or classifications. In the engine model, constants defined in Enums are globally available to all other classes, which may have associations to a particular Enum class or reference the values of individual literals in math expressions, in WHERE conditions on queries, or filters at the Application schema level.
An Enum class is distinguishable in the diagram from the stereotypical «enum», and by the presence of two lists: attributes and literal objects.
An Enum class
Create an Enum #
Right-click on a free spot in the workspace (Canvas) to open the Database menu; from the drop-down menu choose New enum class. Alternatively, click on the palette button(Create a new enum).
The attribute name will be created automatically.
Literals #
A literal is a constant object with global visibility; in the simplest form it is a string, or more precisely an object with a single name attribute of type string, with a unique uppercase value in the context of the Enum class. The name attribute is mandatory, since it identifies the literal itself in the list of literal objects, and is always Object title.
Add a literal #
Right-click on an Enum class to open its Class menu and select New literal; once the literal is added, the count of total objects in the class will increase by one.
Multi-attribute literals #
Through literals it is possible to represent structured information by defining other attributes on the Enum class (besides name).
All platform attributes and all native attributes except Serial and File are allowed, while derived attributes are disabled. By construction, it is not possible to declare unique constraints, domain restrictions or indexes on Enum attributes, nor set them as required; the only required attribute is name.
Ordering of literals #
Although it is possible to freely arrange literals within the class as it is for attributes (via drag and drop), any changes made in this context simply impact the readability of the engine model, but have no effect on the arrangement of literal objects outside the Designer.
However, there are scenarios in which it may be desirable to change the order of literals at the application level; for example, to improve the user experience, one might want the most common choices to appear at the top of a drop-down menu list. This requires adding at least one other attribute to the Enum class (in addition to the name attribute), and using that attribute as a parameter to sort or filter the results. More information is available in the following section.
Modifying literals #
The literals fields can be filled in through a dedicated editor. To open it, you need to open the Class menu of the Enum by right-clicking on it, and select the Edit literal objects option.
In the example shown in the figure we have added the attribute discount_percentage to the Enum Discount_code. The values of this attribute for the two literals in the class were changed by filling in the fields in the table visible on the right.
Referencing an Enum #
A first way to use an Enum in the engine model is to create associations towards it, so you can associate an object to one of the declared literals. The only relationships allowed with Enum classes are unidirectional associations, with the Enum as target; thus only roles towards the Enum are navigable, with Exactly one (1) or Zero or one (01) cardinalities.
It is also possible to refer to Enum literals in expressions with the following syntax: <EnumClassName>[LITERAL_NAME].name. The (Enum constants) in the Expression editor shows the list of all Enums in the model, and for each of them, the list of literals; for each literal, you can then select the attributes declared on the Enum, as well as all of its platform attributes. This allows you to remove hardwired values from expressions and instead refer to information directly available in the engne model.
Enum in the generated application #
Examples #
Enum with a single attribute #
Let’s see an example of an Enum class: we have modeled a shipment (Shipping) and we want to be able to control its progress. To represent the possible states of the shipment we could have used native attribute; however, since it is static information (that therefore will not be modified at database level) it is more effective to bind this information to the model through an Enum. We therefore created the Enum class Shipping_status with the literals DELIVERED, IN_TRANSIT, OUT_FOR_DELIVERY, PENDING, SHIPPED and CANCELED.
The query status points to the attribute name, which has the names of the literals as values.
The math attribute/completed: boolean simply indicates whether the shipment was completed or not by referencing via square brackets a literal in its expression: Shipment_state[DELIVERED]. name=state.. This way, when /status has DELIVERED as its value it is TRUE, and therefore the shipment is completed.
In the next figure, /completed has been selected; the Designer shows the attributes and the literal used to calculate it circled in red.
Enum with multiple attributes #
Let’s now look at the example of a slightly more complex Enum. We have modeled a set of discount codes (Discount_code) that can be applied to the value of a sale (Sale).
The /total_price attribute is calculated by summing the values found by the query pointing at the price (price) of the products (Product). The discount_percentage attribute, added to the Discount_code Enum, indicates the percentage discount applied. We created a query on Sale that points to this attribute, so we can use it to calculate the final price. The association to Discount_code is Zero or one (01) because the discount code can also not be applied.
To obtain the final discounted price, we finally created a math attribute, total_discounted_price, which multiplies the total price of the sale by the percentage discount applied, through the expression total_price * discount_percentage.
