CUBA Platform. Developer’s Manual

Select Customer entity in the Data Model tab on the navigation panel to create standard screens for viewing and editing Customers. Click New > Generic UI screen at the top of the section. After that, the template browser page will appear.

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

All fields in this dialog are already populated with default values, there is no need to change them. Click Create and then Close buttons.

customer-browse.xml and customer-edit.xml items will appear in Web Module on Generic UI tab of the navigation panel.

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 tab on the navigation panel, select the Order entity and click the New > View button. View designer page will open. Enter order-with-customer as the view name, click on customer attribute and select _minimal view for the Customer entity on the panel on the right.

Click OK on the top panel.

After that, select the Order entity and click New > Generic UI screen.

Select order-with-customer in the View fields for both browser and editor templates and click Create.

order-edit.xml and order-browse.xml items will appear in the Web Module on the Generic UI tab of the navigation panel.

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 tab on the navigation panel and click Open web menu. The Menu Designer page will open. Select the application-sales menu item to edit its properties.

Enter the new value of the menu identifier − shop − in the Id field, then click OK on the top panel.

Do the following to display the list of Orders in the Customer’s edit screen:

If we want to run the discount calculation when a user clicks a button on the customer’s browser screen, the most straightforward way to accomplish this is to put the calculation logic right in the browser screen controller.

See the Calculate discount button in the demo application and the screen controller implementation: CustomerBrowse.java. Please keep in mind that the provided calculation process is not optimal and see more options in the Loading and Saving Data section.

This approach is acceptable if the logic is invoked from a single point and it is not too complex to fit into a couple of short methods.

Let’s complicate the task from the previous section a bit. Now we want to invoke the calculation both from the customer browser and editor screens. To not repeat yourself, we should extract the logic to a common place available for both controllers. It can be a managed bean of the client tier.

A managed bean is a class annotated with the @Component annotation. It can be injected into other beans and screen controllers, or obtained via the AppBeans.get() static method. If the bean has a separate interface, you can access the bean through the interface instead of the class.

Please note that in order to be accessible for screen controllers, the bean must be located in global, gui or web modules of your project. In the former case the bean will be also accessible for the middleware.

See the Calculate discount button on both browser and editor screens of the demo application and the implementation:

In the previous section we considered the encapsulation of business logic in a managed bean of the client tier. Now we will go further and implement our logic in the most appropriate place: on the middle tier. By doing this, we will achieve the following goals:

In order to invoke a middleware business method from the client, you need to create a service. Studio can help you to scaffold the service stub:

See an example implementation in the demo application:

Let’s now make our business method accessible for external clients through the REST API:

Studio will create the rest-services.xml file and write the method description into it. After restarting the application server you will be able to invoke your business method using HTTP requests. For example, the following GET request should work with our online demo server:

https://demo1.cuba-platform.com/business-logic/rest/v2/services/sample_DiscountService/calculateDiscount?customerId=1797f54d-5bec-87a6-4330-d958955743a2

Please note that the demo application allows anonymous access. In the most real-world usage scenarios you need to authenticate prior to executing REST requests.

Entity listeners allow you to execute your business logic each time an entity is added, updated or removed from the database. For example, we could recalculate the discount for a customer each time an order for this customer is changed.

An entity listener stub can be easily created using Studio:

See an example implementation in the demo application:

If you open the Logic in Entity Listeners screen of the demo application, you will see two tables: orders and customers. Create, edit or remove an order, then refresh the customers table, and you will see that the discount of the corresponding customer is changed.

With JMX beans you can expose some administrative functionality of your application without creating a user interface for it. The functionality becomes available via the built-in JMX console and via external JMX tools like jconsole.

In our example with discounts, a user having access to JMX console is able to recalculate discounts for all customers and for a customer with a given id.

Studio cannot help you with scaffolding JMX beans at the moment, so all classes and configuration entries have to be created manually in the IDE.

See an example implementation in the demo application:

Sometimes you need to run some code on the application startup, at the moment when all application functionality is already initialized and ready to work. For this, you can use application lifecycle event listeners.

In this section we demonstrate how to dynamically register an entity listener on application startup. Consider the following task: a project has an Employee entity that is linked one-to-one to the platform’s User entity.

If the name attribute of the User entity is changed, for example, through a standard user management screen, the name attribute of the related Employee should change as well. This is a common task for "denormalized" data, which is typically solved using entity listeners. Our case is more complicated, since we need to track changes of the platform’s User entity, and thus we cannot add an entity listener using the @Listeners annotation. So we will add a listener dynamically using the EntityListenerManager bean on application start.

As a result, the initEntityListeners() method of the AppLifecycle class will be invoked on the middleware block startup. This method registers the sample_UserEntityListener bean as an entity listener for the User entity.

The onBeforeUpdate() method of the UserEntityListener class will be invoked every time before the changes in the User instances are saved to the database. The method checks if the name attribute exists among the updated attributes. If yes, a related Employee instance is loaded and its name is updated with the new value.

There are different ways to assign initial values to the attributes of new entity instances.

CUBA platform supports two types of relationship between entities: association and composition. They are called ASSOCIATION and COMPOSITION respectively in the CUBA Studio interface. Association is a relationship between the objects that can exist separately from each other. Composition, on the other hand, is used for "master-detail" relations, when the detail instances can exist only as part of the master. A case of an airport and its terminals may be considered an example of composition: a terminal that does not belong to any airport does not make sense.

Typically, the entities belonging to a composition are edited together since it is more natural. For example, a user opens the airport editing screen and sees the list of terminals, so the user can create and edit them, but all changes both for the airport and the terminals are saved to the database together in one transaction, and only after the user confirms saving of the master entity (the airport).

The many-to-many association implies that multiple records in one table are related to multiple records in another table. The joining table will store primary keys of both related entities. Optionally, this table may contain additional columns.

Depending on whether you need additional fields in the joining table, you can implement many-to-many relationship with an additional entity or without it. The following examples illustrate both approaches.

This section demonstrates how to use entity inheritance in CUBA applications.

Let’s assume that we have two types of clients - companies and individuals, which have some common attributes. We would like to store the common attributes in one table and use separate linked tables to store specific attributes.

So, the data model contains the Client entity, which is a base class stored in the SAMPLE_CLIENT table. The Company and Person entities are stored in separate tables with foreign keys that reference the base table.

The Order entity has a reference to Client. As the client can be of the different types, when users create orders, they should be able to choose the type of the client.

Client.java entity:

Company.java entity:

Person.java entity:

The OrderEdit.java screen controller contain the Client selection components and logic.

Below we explain how to properly place visual components and containers on your screens.

Passing parameters from one screen to another is one of the most common tasks in UI development. Let’s consider this task taking an "order management" application as an example.

The methods used for opening screens (openWindow(), openLookup(), openEditor()) also allow you to get values back from these screens.

It is often convenient to edit the One-to-One composition in one single editor. Let’s see how it can be implemented taking the Customer and the CustomerDetails relationship as an example.

Now, both linked entities can be created and edited in one editor screen.

Using the FieldGroup component in an entity’s editor is not mandatory. You can easily replace it with separate fields to create a custom screen layout.

Below is an example of such editor for the Order entity.

The order-edit.xml descriptor contains the main orderDs and the nested orderLinesDs datasources, as well as the independent customersDs datasource for selecting a customer in a lookupField:

Now, all we have to do is to create the fields for the Order attributes, bind them to the appropriate datasources and define the entity’s attribute using the property attribute:

This approach is more flexible in terms of screen layout design. You can select any visual components for the fields, group the fields and place them wherever you like on the screen.

Both DataManager and EntityManager can be used for CRUD operations on entities. There are the following differences between these interfaces:

DataManager in fact delegates to DataStore implementations, so the DataManager features listed below apply only to the most common case when you work with entities located in a relational database:

When you work with data on the client tier, you have only one option - DataManager. On the middleware, use EntityManager when you need to implement some atomic logic inside a transaction or if the EntityManager interface is better suited to the task. Otherwise, on the middleware you can use both.

If you need to overcome restrictions of DataManager when working on the client tier, create your own service and use EntityManager to work with data. In the service, you can check permissions using the Security interface and return data to the client in the form of persistent or non-persistent entities or arbitrary values.

An OAuth token is required for any REST API method (except when you are using an anonymous access). A token can be obtained by the POST request on the address:

http://localhost:8080/app/rest/v2/oauth/token

An access to this endpoint is protected with a basic authentication. REST API client identifier and password is used for basic authentication. Please note that these are not an application user login and password. REST API client id and password are defined in the application properties cuba.rest.client.id and cuba.rest.client.secret (the default values are client and secret). You must pass the client id and secret, separated by a single colon (":") character, within a base64 encoded string in the Authorization header.

The request type must be application/x-www-form-urlencoded, the encoding is UTF-8.

The request must contain the following parameters:

You can also use cURL:

Method returns a JSON object:

An access token value is in the access_token property.

In order to use the access token, put it in the Authorization header with the Bearer type, for example:

The refresh_token property contains a refresh token value. A refresh token cannot be used for accessing the protected resources, but it has a longer lifetime than an access token and it can be used to obtain new access token when the current one is expired.

The request for getting new access token using the refresh token must contain the following parameters:

See also the following application properties related to tokens:

LDAP Authentication for REST can be enabled using the following properties:

Example of local.app.properties file:

You can obtain OAuth token using the following end-point:

http://localhost:8080/app/rest/v2/ldap/token

An access to this endpoint is protected with the basic authentication. REST API client identifier and password are used for basic authentication. Please note that these are not the application user login and password. REST API client id and password are defined in the application properties cuba.rest.client.id and cuba.rest.client.secret (the default values are client and secret). You must pass the client id and secret, separated by a single colon (":") character, within a base64 encoded string in the Authorization header.

Request parameters are the same as for standard authentication:

The request type must be application/x-www-form-urlencoded, the encoding is UTF-8.

Also, standard authentication with login and password can be disabled:

Authentication mechanisms can provide access tokens by key, link, LDAP login and password, etc. REST API uses its own authentication mechanism that cannot be modified. In order to use custom authentication process, you need to create a REST controller and use its URL.

Let’s consider the custom authentication mechanism that enables getting an OAuth token by a promo code. In the following example we will use a sample application that contains the Coupon entity with code attribute. We will send this attribute’s value as an authentication parameter in GET request.

Let’s suppose that the system has a sales$Order entity and we need to get a list of this entity instances. Besides, we need to get not all the records, but only 50 records, starting with the 100th one. A response must contain not only simple properties of the sales$Order entity but also an information about the order customer (a reference field named customer). Orders must be sorted by date.

A base URL for getting all instances of the sales$Order entity is as follows:

http://localhost:8080/app/rest/v2/entities/sales$Order

To implement all the conditions described above the following request parameters must be specified:

An OAuth token must be put in the Authorization header with the Bearer type:

As a result, we get the following GET request URL:

http://localhost:8080/app/rest/v2/entities/sales$Order?view=order-edit-view&limit=50&offset=100&sort=date

Using cURL, the request will look like:

The response will be like this:

Please note, that every entity in the response has a _entityName attribute with the entity name and an _instanceName attribute with the entity instance name.

New sales$Order entity instance can be created with the POST request on the address:

http://localhost:8080/app/rest/v2/entities/sales$Order

An OAuth token must be put in the Authorization header with the Bearer type.

The request body must contain a JSON object that describes a new entity instance, e.g.:

Below is an example of cURL POST request that creates a new Order instance:

A collection of order items (items) and a customer reference are passed in the request body. Let’s examine how these attributes will be processed.

First, let’s have a quick look to the Order class:

The items collection property is annotated with the @Composition. REST API methods for entity creation and update will create a new entity instances for all members of such collections. In our case, two instances of OrderItem entity will be created with the Order entity.

The customer reference doesn’t have a @Composition annotation, that’s why the REST API will try to find a client with the given id and set it to the customer field. If the client is not found then an order won’t be created and the method will return an error.

In case of successful method execution a full object graph of the created entity is returned:

An existing sales$Order entity instance can be updated with the PUT request on the address:

http://localhost:8080/app/rest/v2/entities/sales$Order/5d7ff8e3-7828-ba94-d6ba-155c5c4f2a50

The last part of the query here is the entity identifier.

An OAuth token must be put in the Authorization header with the Bearer type.

The request body must contain a JSON object containing only fields we want to update, e.g.:

The response body will contain a modified entity:

Before the execution with the REST API a query must be described in the configuration file. The rest-queries.xml file must be created in the main package of the web module (e.g. com.company.sales). Then the file must be defined in the application properties file of the web module (web-app.properties).

rest-queries.xml contents:

To execute a JPQL query the following GET request must be executed:

http://localhost:8080/app/rest/v2/queries/sales$Order/ordersAfterDate?startDate=2016-11-01&endDate=2017-11-01

The request URL parts:

An OAuth token must be put in the Authorization header with the Bearer type.

The method returns a JSON array of extracted entity instances:

A full list of possible request parameters is available in the Swagger documentation.

It is also possible to execute a query with POST HTTP request. POST request can be used when you need to pass a collection as query parameter value. In this case, the type of the query parameter in REST queries configuration file must end with square brackets: java.lang.String[], java.util.UUID[], etc.

Query parameters values must be passed in the request body as JSON map:

The POST request URL:

http://localhost:8080/app/rest/v2/queries/sales$Order/ordersByIds?returnCount=true

Suppose there is an OrderService service in the system. The implementation looks as follows:

Before the execution with the REST API a service method invocation must be allowed in the configuration file. The rest-services.xml file must be created in the main package of the web module (e.g. com.company.sales). Then the file must be defined in the application properties file of the web module (web-app.properties).

rest-services.xml content:

To invoke the service method the following GET request must be executed:

http://localhost:8080/app/rest/v2/services/sales_OrderService/calculatePrice?orderNumber=00001

The request URL parts:

An OAuth token must be put in the Authorization header with the Bearer type.

A service method may return a result of simple datatype, an entity, an entities collection or a serializable POJO. In our case a BigDecimal is returned, so the response body contains just a number:

REST API allows execution not only of methods that have arguments of simple datatypes, but also of methods with the following arguments:

Suppose we added a new method to the OrderService created in the previous section:

OrderValidationResult class looks as follows:

The new method has an Order entity in the arguments list and returns a POJO.

Before the invocation with the REST API the method must be allowed, so we add a record to the rest-services.xml configuration file (it was described in the Service Method Invocation (GET)).

The validateOrder service method may be called with the POST request on the address:

http://localhost:8080/app/rest/v2/services/sales_OrderService/validateOrder

In case of the POST request parameters are passed in the request body. The request body must contain a JSON object, each field of this object corresponds to the service method argument.

An OAuth token must be put in the Authorization header with the Bearer type.

The REST API method returns a serialized POJO:

When downloading a file, passing a security token in the request header is often inconvenient. It is desirable to have a URL for downloading that may be put to the src attribute of the img tag.

As a solution, an OAuth token can also be passed in the request URL as a parameter with the access_token name.

For example, an image is uploaded to the application. Its FileDescriptor id is 44809679-e81c-e5ae-dd81-f56f223761d6.

In this case a URL for downloading the image will look like this:

http://localhost:8080/app/rest/v2/files/44809679-e81c-e5ae-dd81-f56f223761d6?access_token=a2f0bb4e-773f-6b59-3450-3934cbf0a2d6

In order to upload a file, you should get an access token which will be used in the subsequent requests.

Suppose we have the following form for the file input:

We will use jQuery for the upload and get a JSON with data which is the newly created FileDescriptor instance. We can access the uploaded file by its FileDescriptor id with the access token as a parameter:

This section contains an example of using REST API v2 from JavaScript running on a HTML page. The page initially shows login form, and after successful login displays a message and a list of entities.

For simplicity, we will use modules/web/web/VAADIN folder for storing HTML/CSS/JavaScript files, as the corresponding folder in the deployed web application is used for serving static resources by default. So you will not need to make any configuration of your Tomcat application server. The resulting URL will start from http://localhost:8080/app/VAADIN, so do not use this approach in a real world application - create a separate web application with its own context instead.

Download jQuery and Bootstrap and copy to modules/web/web/VAADIN folder of your project. Create customers.html and customers.js files, so the content of the folder should look as follows:

customers.html file content:

customers.js file content:

Login and password from the user input are sent to the server by the POST request with the Base64-encoded client credentials in the Authorization header as explained in Getting an OAuth Token section. If the authentication is successful, the web page receives an access token value from the server, the token is stored in the oauthToken variable, the loginForm div is hidden and the loggedInStatus div is shown.

To show the list of customers, the request is sent to the server to get the instances of the sales$Customer entity, passing the oauthToken value in the Authorization header.

In case the request is processed successfully, the customers div is shown, and the customersList element is filled with items containing customer names and emails.

There are methods in the REST API for getting localized messages for entities, their properties and enums.

For example, to get a list of localized messages for the sec$User entity you have to execute the following GET request:

http://localhost:8080/app/rest/v2/messages/entities/sec$User

An OAuth token must be put in the Authorization header with the Bearer type.

You can explicitly specify the desired locale using the Accept-Language http header.

The response will be like this: