CUBA Platform. Developer’s Manual

Right-click on Customer entity in the Data Model section of the CUBA project tree, and in its context menu select New > Screen to create standard screens for viewing and editing Customer instances. After that, the template browser page will appear.

Select Entity browser and editor screens in the list of available templates and click Next.

All fields in this dialog are already populated with default values, there is no need to change them. Click Next, leave localizable messages unchanged on the next screen and click Finish .

The screen files will appear in the Screens section of the Generic UI tree section:

The Order entity has the following distinction: since one of the attributes is the Order.customer reference attribute, you should define a view including this attribute (standard _local view does not include reference attributes).

Go to the Data Model section of CUBA project tree, right-click on the Order entity and in its context menu select New > View. View designer page will open. Enter order-with-customer as the view name, click on customer attribute and select the _minimal view for the Customer entity on the panel on the right.

Click OK.

After that, select the Order entity and in its context menu select New > Screen.

Select Entity browser and editor screens template.

Select order-with-customer as the view for both browser and editor screens and click Next and then Finish on the next screen.

The screen files will appear in the Screens section of the Generic UI tree section:

At the moment of their creation, the screens were added to the application menu item of the default application menu. Let’s rename it. Switch to the Generic UI section of CUBA project tree and open Web Menu. The web-menu.xml descriptor will open.

Change the menu identifier from application-sales to shop either from code or in the visual designer on the Structure tab.

Then, open the messages.properties file in the Main Message Pack section and modify the old caption of the menu item:

Do the following to display the list of orders in the Customer edit screen:

Go to the Generic UI section of CUBA project tree. Open the customer-edit.xml screen for editing.

Switch to the Designer tab.

In the components palette find Collection in the Data components group. Drag this component to the data section in screen components hierarchy panel.

Select the com.company.sales.entity.Order entity and its _local view for the data container. Generate the loader ID using the button.

Add the WHERE clause to the generated query to select only the orders that have a reference to the edited customer:

Finally, you should see a data container which will load the Order instances in customer-edit screen XML descriptor:

Then, drag Label from the components palette to components hierarchy panel and place it between form and editActions. Go to the Properties tab on the properties panel. Enter Orders in the value field.

Drag Table from the components palette to components hierarchy panel and place it between label and editActions. Select this component in the hierarchy and specify table size in the Properties tab: set 300px in the width field and 200px in the height field. Choose ordersDc from the list of available data containers. Then generate the table identifier using the button next to the id field: ordersTable.

Next, right-click on the table and select Wrap Into > Group Box from the context menu. Go to the Properties tab on the properties panel of this group box and enter Orders in the caption field and set group box width to 320 px.

As a result, the customer-edit.xml code on the Text tab will look as follows:

Open the CustomerEdit screen controller. The and buttons on the gutter enable quick switching between the screen descriptor and controller.

First - we need to disable automatic data load for the screen, because we need custom data load process. To disable automatic data load, remove @LoadDataBeforeShow annotation from the class.

Inject the orders loader in the controller class by pressing Alt+Insert inside the class definition and selecting ordersDl from the list. Or you can just type the following code manually:

Then, subscribe to the BeforeShowEvent to set the customer parameter value for the ordersDl data loader. To do this, click Alt+Insert znd select Subscribe to Event > BeforeShowEvent in the Generate menu. And, of course, you can just add the following code manually.

This method will be in charge of loading related Order instances.

The framework enables building multi-tiered applications with the distinct client, middle and database tiers. Further on, we will consider mainly the middle and client tiers, so the words "all tiers" will refer to these tiers only.

An application can have one or more blocks on each tier. A block is a separate executable program interacting with other blocks of the application. Usually, a block is a web application running on JVM.

Middleware is the mandatory block for any application. User interface can be implemented by one or several blocks, such as Web Client and Web Portal.

All of the Java-based client blocks interact with the middle tier uniformly via HTTP protocol which enables deploying the middle tier arbitrarily, behind a firewall as well. In the simplest case, when the middle tier and the web client are deployed on the same server, local interaction between them can bypass the network stack for better performance.

A module is the smallest structural part of a CUBA application. It is a single module of an application project and the corresponding JAR file with executable code.

Standard modules:

The framework enables splitting the application functionality into components. Each application component (AKA add-on) can have its own data model, business logic and user interface. The application uses the component as a library and includes its functionality.

The concept of application components allows us to keep the framework relatively small, while delivering optional business functionality in the components like Reporting, Full-Text Search, Charts, WebDAV and others. At the same time, the application developers can use this mechanism to decompose large projects into a set of functional modules which can be developed independently and have a different release cycle. Of course, application components can be reusable and provide a domain-specific layer of abstraction on top of the framework.

Technically, the core framework is also an application component called cuba. The only difference is that it is mandatory for any application. All other components depend on cuba and can also have dependencies between each other.

Below is a diagram showing dependencies between the standard components typically used in an application. Solid lines demonstrate mandatory dependencies, dashed lines mean optional ones.

The following diagram illustrates a possible structure of dependencies between standard and custom application components.

Any CUBA application can be easily turned into a component and provide some functionality to another application. In order to be used as a component, an application project should contain an app-component.xml descriptor and a special entry in the manifest of the global module JAR. CUBA Studio allows you to generate the descriptor and manifest entry for the current project automatically.

See the step-by-step guide to working with a custom application component in the Example of Application Component section.

The above-listed architectural principles are directly reflected in the structure of the assembled application. Suppose we have a simple application which has two blocks – Middleware and Web Client; and includes the functionality of two application components - cuba and reports.

The figure demonstrates the contents of several directories of the Tomcat server with the deployed application.

The Middleware block is represented by the app-core web application, the Web Client block – by the app web application. The web applications contain the JAR files located in the WEB-INF/lib directories. Each JAR (artifact) is a result of building a single module of an application or one of its components.

For instance, the set of JAR files of the app-core web application is determined by the fact that the Middleware block includes global and core modules; and the application uses cuba and reports components.

Data model entities are divided into two categories:

The entities are characterized by their attributes. An attribute corresponds to a field and a pair of access methods (get / set) of the field. If the setter is omitted, the attribute becomes read-only.

Persistent entities may include attributes that are not stored in the database. For a non-persistent attribute, the field is optional and you can create only access methods.

The entity class should meet the following requirements:

The following types can be used for entity attributes:

Base entity classes (see below) override equals() and hashCode() methods to check entity instances equivalence by comparing their identifiers. I.e., instances of the same class are considered equal if their identifiers are equal.

Metadata framework is used to support efficient work with data model in CUBA-applications. The framework:

When retrieving entities from the database, we often face the question: how to ensure loading of related entities to the desired depth?

For example, you need to display the date and amount together with the Customer name in the Orders browser, which means that you need to fetch the related Customer instance. And for the Order editor screen, you need to fetch the collection of Items, in addition to that each Item should contain a related Product instance to display its name.

Lazy loading can not help in most cases because data processing is usually performed not in the transaction where the entities were loaded but, for example, on the client tier in UI. At the same time, it is unacceptable to apply eager fetching using entity annotations as it leads to constant retrieval of the entire graph of related entities which can be very large.

Another similar problem is the requirement to limit the set of local entity attributes of the loaded graph: for example, some entity can have 50 attributes, including BLOB, but only 10 attributes need to be displayed on the screen. In this case, why should we download 40 remaining attributes from the database, then serialize them and transfer to the client when it does not need them at the moment?

Views mechanism resolves these issues by retrieving from the database and transmitting to the client entity graphs limited by depth and by attributes. A view is a descriptor of the object graph required for a certain UI screen or data-processing operation.

Views processing is performed in the following way:

A view is determined by an instance of the View class, where:

ViewProperty class has the following properties:

Managed Beans are program components intended for implementation of the application’s business logic. "Managed" in this case means that the instance creation and dependency management is handled by the container, which is the main part of the Spring framework.

Sometimes, it is necessary to give system administrator an ability to view and change the state of some managed bean at runtime. In such case, it is recommended to create a JMX bean – a program component having the JMX interface. JMX bean is usually a wrapper delegating calls to the managed bean which actually maintains state: cache, configuration data or statistics.

As you can see from the diagram, the JMX bean consists of the interface and the implementation class. The class should be a managed bean, i.e., should have the @Component annotation and unique name. The interface of the JMX bean is registered in spring.xml in a special way to create the JMX interface in the current JVM.

Calls to all JMX bean interface methods are intercepted using Spring AOP by the MBeanInterceptor interceptor class, which sets the correct ClassLoader in the current thread and enables logging of unhandled exceptions.

JMX-interface can be utilized by external tools, such as jconsole or jvisualvm. In addition, the Web Client platform block includes the JMX console, which provides the basic tools to view the status and call the methods of the JMX beans.

Infrastructure interfaces provide access to frequently used functionality of the platform. Most of them are located in the global module and can be used both on the middle and client tiers. However, some of them (Persistence, for example) are accessible only for Middleware code.

Infrastructure interfaces are implemented by Spring Framework beans, so they can be injected into any other managed components (managed beans, Middleware services, generic user interface screen controllers).

Also, like any other beans, infrastructure interfaces can be obtained using static methods of AppBeans class, and can be used in non-managed components (POJO, helper classes etc.).

AppContext is a system class, which stores references to certain common components for each application block in its static fields: