Entity Designer

Studio provides a visual designer that simplifies entity creation, so you don’t need to remember all the rules and annotations.

This feature is free to use in small projects with up to 10 entities and roles. In a larger project, it requires a RAD or Enterprise subscription.

JPA Entity Designer

To create a JPA entity, use the menu in the Jmix Tool Window.

new

The New JPA Entity dialog appears.

entity create

Fill in the fields:

  • Class - the name of the new class. It must comply with Java name requirements.

  • Package - the package that the class will reside in. The default value automatically appears in the field. You can change it, and Studio creates the package after you click OK.

  • Entity type - select the type of entity:

    • Entity - a class to be a data model entity.

    • MappedSuperclass - a base superclass that is not associated with any particular database table. A such entity class is annotated by @MappedSuperclass.

    • Embeddable - an embeddable persistent entity. A such entity class is annotated by @Embeddable.

  • Parent - the class that your new class inherits from.

  • Id type - select the type of the entity primary key:

    • UUID - the identifier of the UUID type.

    • Long - the identifier of the Long type. It’s highly recommended to add the UUID trait, as it enables some optimizations and allows you to identify your instances uniquely in a distributed environment.

    • Integer - the identifier of the Integer type. It’s highly recommended to add the UUID trait, as it enables some optimizations and allows you to identify your instances uniquely in a distributed environment.

    • String - the identifier of the String type. It’s highly recommended to add the UUID trait, as it enables some optimizations and allows you to identify your instances uniquely in a distributed environment. The concrete entity class must have a string field annotated with the @Id JPA annotation.

    • Embedded - the primary key is a composite key. In this case, the concrete entity class has a field of the embeddable type representing the key, annotated with the @EmbeddedId JPA annotation.

  • Id value - in the case of the UUID id type, this field is enabled and has the Generated By Jmix value. In the general case, the Id value dropdown has the values listed below:

    • Generated By Jmix. The id of the entity has the @JmixGeneratedValue annotation.

    • Identity column is suitable only for Integer and Long id types. The id of the entity has the @GeneratedValue JPA annotation with the GenerationType.IDENTITY strategy. The Identity column value is used for the auto-incremented identifiers. It’s highly recommended to add the UUID trait, as it enables some optimizations and allows you to identify your instances uniquely in a distributed environment.

    • Assigned by user - the id is set by the user. It is suitable for Integer, Long, String, and Embedded id types.

  • Id length appears if the String id type is selected. Specify the maximum number of characters. The default value is 255.

  • Composite id type appears if the Embedded id type is selected. Select the embeddable entity representing a composite key.

  • In the Traits checkbox group, select the necessary traits.

Then click OK.

Studio displays three tabs for the created entity. Together they form the visual Entity Designer:

  • Text contains the source code of the entity.

  • Designer shows the entity structure. You can add entity attributes, set an instance name, an inheritance strategy, and validations using a graphical interface instead of writing Java code.

  • Indexes displays indexes and allows you to create new ones.

Actions Panel

The actions panel is located on the top of the entity designer. It provides access to the following actions:

  • Views - navigates to existing views or creates new views for the current entity.

    entity designer create screen

  • Event Listeners - navigates to existing event listeners or creates a new one for the current entity:

    entity designer create listener

  • Lifecycle Callbacks - adds lifecycle callbacks method stubs:

    entity designer lifecycle callbacks

Designer Tab

The Designer tab shows the entity structure:

entity designer designer

In addition to the fields described in the JPA Entity Designer dialog, the Designer tab contains the following fields:

  • The Instance name dropdown.

  • The DB view checkbox. Using this checkbox you can map a JPA Entity to the database view. A such entity class is annotated by the @DbView annotation.

  • The DDL Generation Settings link button opens the visual constructor of a @DdlGeneration annotation value:

    ddl generation

  • The Traits link button opens the dialog containing traits:

    traits

  • In the Inheritance dropdown, you can select the inheritance strategy.

  • Using the Comment edit link, you can add comments to an entity.

The Attributes panel contains the actions for managing entity attributes:

  • The Add (add) button opens the New Attribute dialog.

  • Click the Copy (copy) button to create a copy of the existing attribute.

  • The Add to Views (add attribute to screens) button opens a dialog that shows all views that display the current entity. Select the views that will display the selected attribute.

    attributes collection modified

  • Click the Remove (remove) button to remove the selected attribute.

  • Use the Up (move up) / Down (move down) buttons to reorder the attributes.

The right panel of the entity designer shows the properties of the selected attribute:

  • Use the globe (globe) button next to the Name field to set a user-friendly name for the attribute.

  • The Attribute type and Type dropdowns allow you to select the type of entity attribute.

  • Using the Comment edit link, you can add comments to an entity attribute.

The Validation panel is used for defining the constraints of bean validation. Click on the link button next to the selected constraint. The constraint editor opens:

email validation

Text Tab

In the Text tab, you can see the resulting entity class generated by the designer.

entity designer text

If you have an experience with JPA, you will see familiar annotations: @Entity, @Table, @Column, etc. There are also a few annotations specific to Jmix. The most important one is @JmixEntity on the class header. In general, any POJO can be an entity in Jmix if it is annotated with @JmixEntity.

The entity class can be edited manually, and when you switch back to the Designer tab, it will reflect the changes. For example, if you remove the nullable = false and @NotNull from an attribute, the designer will unselect the Mandatory checkbox for it.

The actions panel is located on the top of the source code editor. The following actions are added to the actions described above:

  • Add Attribute - opens a New Attribute dialog.

  • Add Attributes to Views - opens an Add Attributes to Views dialog which shows all views that display the current entity. Select the attributes which should be appended to views.

    add attribute to views

Indexes Tab

The Indexes tab is used to define unique indexes.

entity designer index

To create a new index, click the New Index (add) button in the Database Indexes toolbar. Studio will add a row to the indexes list.

Select an entity attribute or a set of attributes in the Available attributes list and click the arrow arrow right to move it to the Selected attributes.

Select the Unique and / or Constraint checkboxes in the index row.

Adding Attributes

You can add attributes by clicking the Add (add) button in the Designer tab and configuring the attribute in the appeared dialog. In the example below, the addresses attribute with the Attribute type ASSOCIATION is added. In this case, for one-to-many reference, you need to create an inverse attribute in the Address entity.

entity association

The globe button in the right part of the Name field lets you immediately set a user-friendly name for the attribute. It is stored in the messages.properties file and used by default in UI components.

entity message

Also, you can call the creation attribute dialog in the Text tab clicking Add Attribute on the top panel or in the Generate popup.

entity generate

Creating Instance Name

Studio sets an instance name for an entity automatically when an attribute with one of the following names is added to the entity: name, title, caption, label, summary, description, firstName, lastName, middleName.

When you want to set another attribute for generating an instance name, use the visual constructor. You can open it by clicking the pencil button in the Instance name field.

entity instance editor

The instance name can also be created in the Text tab. Position the cursor on the class name, click Alt+Enter (⌥↩) and select Add instance name.

entity instance text

DTO Entity Designer

To create a DTO entity, click New (add) → DTO Entity in the Jmix Tool Window. The New DTO Entity dialog appears.

dto entity

The displayed fields are similar to the JPA entity fields. Fill in the fields and click OK.

Studio displays two tabs for the created entity.

  • Text contains the source code of the DTO entity.

  • Designer shows the entity structure.

Enumeration Designer

Studio helps to work with enumerations by providing a set of actions and the visual designer. To create an enumeration, click New (add) → Enumeration in the Jmix Tool Window.

When the enumeration is created, its class will be opened in the editor with two tabs.

entity enum editor

  • Text contains the source code.

  • Designer shows the enumeration designer, where you can configure the enumeration and its values using a graphical interface instead of writing Java code.

Use the Values table and its associated buttons to set up enumeration constants.

  • Name column allows you to enter the enumeration constant name to be used in the code. It can be renamed later without affecting existing data in the database.

  • Value column allows entering the id of the enumeration constant. This is the actual value stored in the database.

The globe button allows you to set localized captions for the selected enumeration constant.

Designer also provides the ability to change the id type used by the enumeration from String to Integer and vice versa. Studio will migrate usages of the enumeration in the code. After that, you should change the values of the existing enumeration constants.

Such migration does not migrate enumeration values already stored in the database tables. You will need to implement such migration yourself.