Платформа CUBA. Руководство по разработке приложений

Для создания стандартных экранов просмотра и редактирования покупателей необходимо выделить сущность Customer на вкладке Data Model панели навигатора и нажать на кнопку New > Generic UI screen внизу панели. После этого на экране отобразится страница создания стандартных экранов сущности.

В списке доступных шаблонов выберите Entity browser and editor screens.

Все поля этого окна заполнены значениями по умолчанию, пока не будем их менять. Нажмите на кнопку Create и затем Close.

Во вкладке Generic UI панели навигатора в модуле Web Module появятся элементы customer-browse.xml и customer-edit.xml.

Сущность Order (Заказ) имеет следующую особенность: так как среди прочих атрибутов существует ссылочный атрибут Order.customer, требуется определить представление сущности Order, включающее этот атрибут (стандартное представление _local не включает ссылочных атрибутов).

Для этого перейдите на вкладку Data Model на панели навигатора, выделите сущность Order и выберите New > View. Отобразится страница дизайнера представлений. В качестве имени введите order-with-customer, в списке атрибутов нажмите на атрибут customer и на отобразившейся справа панели выберите представление _minimal для сущности Customer.

Нажмите на кнопку OK в верхней панели.

Далее выделите сущность Order и выберите New > Generic UI screen.

В отобразившемся окне выберите представление order-with-customer в полях View для браузера и редактора и нажмите на кнопку Create и, затем, Close.

Во вкладке Generic UI панели навигатора в модуле Web Module появятся элементы order-edit.xml и order-browse.xml.

При создании экраны были добавлены в пункт меню application, имеющийся по умолчанию. Переименуем его. Для этого перейдите на вкладку Generic UI на панели навигатора и нажмите на ссылку Open web menu. Отобразится страница дизайнера меню. Выделите пункт меню application-sales для просмотра его свойств.

В поле Id введите новое значение идентификатора меню − shop. После редактирования меню нажмите на кнопку OK в верхней панели.

Займемся задачей отображения списка заказов в окне редактирования покупателя.

Например, необходимо запускать расчет скидки, когда пользователь нажимает кнопку на экране-браузере заказчиков. В этом случае, наиболее простое решение - это разместить логику расчета прямо в контроллере экрана.

См. кнопку Calculate discount в демо-приложении и реализацию контроллера: CustomerBrowse.java. Пожалуйста, имейте в виду, что данная имплементацию расчета не является оптимальной (см. варианты работы с данными в разделе Загрузка и сохранение данных).

Данный подход приемлем, если логика вызывается из одного места и она не слишком сложна, чтобы уместиться в нескольких коротких методах.

Теперь давайте немного усложним задачу из предыдущего раздела. Допустим, требуется вызывать расчет из двух экранов: и из браузера, и из редактора. Чтобы не дублировать код, нужно извлечь код из контроллера и поместить в некоторое общедоступное место. Это может быть управляемый бин клиентского уровня.

Управляемый бин - это класс с аннотацией @Component. Он может быть инжектирован в другие бины и контроллеры экранов, или получен с помощью статического метода AppBeans.get(). Если класс бина реализует некоторый интерфейс, то к нему можно обращаться через этот интерфейс.

Имейте в виду, что для того чтобы бин был доступен для контроллеров экранов, он должен располагаться в одном из следующих модулей: global, gui или web вашего проекта. В случае global, бин будет также доступен на среднем слое.

См. кнопку Calculate discount на экранах браузера и редактора в демо-приложении, и реализацию:

В предыдущем разделе мы рассмотрели инкапсуляцию бизнес-логики в бине клиентского уровня. Теперь мы пойдем дальше и поместим нашу логику в наиболее подходящее место: на средний слой. Сделав это, мы достигнем следующих целей:

Чтобы вызвать бизнес-метод среднего слоя, необходимо создать сервис. Studio может помочь в создании заготовки сервиса:

См. пример реализации в демо-приложении:

Теперь давайте сделаем наш бизнес-метод доступным для внешних клиентов через REST API:

Studio создаст файл rest-services.xml и зарегистрирует в нем метод. После перезапуска сервера вы сможете вызвать метод с помощью HTTP-запросов. Например, следующий GET-запрос должен работать с нашим онлайн демо-сервером:

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

Имейте в виду, что демо-приложение имеет анонимный доступ. В большинстве реальных сценариев использования необходимо будет аутентифицироваться, прежде чем выполнять запросы.

Entity listeners позволяют выполнять бизнес-логику каждый раз, когда сущность создается, изменяется или удаляется в базе данных. Например, мы можем пересчитывать скидку для заказчика каждый раз, когда некоторый заказ для него изменяется.

Заготовку для entity listener можно легко создать в Studio:

См. пример в демо-приложении:

Если вы откроете экран Logic in Entity Listeners демо-приложения, вы увидите две таблицы: заказы и заказчики. Создайте, измените или удалите заказ, обновите таблицу заказчиков, и вы увидите, что скидка для соответствующего заказчика изменилась.

С помощью JMX-бинов можно предоставить доступ к некоторой административной функциональности вашего приложения без создания пользовательского интерфейса для нее. Данная функциональность будет также доступна через встроенную JMX-консоль и через внешние инструменты JMX, например jconsole.

В нашем примере со скидками пользователь, имеющий доступ к JMX-консоли, сможет пересчитывать скидки для всех заказчиков или для заказчика с указанным id.

Studio на данный момент не умеет создавать заготовки JMX-бинов, поэтому все классы и конфигурационные элементы придется создавать вручную в IDE.

См. пример реализации в демо-приложении:

Иногда бывает необходимо выполнить некоторый код сразу после старта приложения в момент, когда все механизмы гарантированно работоспособны. Для этого можно воспользоваться слушателями событий жизненного цикла.

В данном разделе мы рассмотрим, как динамически зарегистрировать для сущности entity listener на старте приложения. Возьмем следующую задачу: в проекте имеется сущность Employee (сотрудник компании), которая связана один-к-одному с платформенной сущностью User (пользователь системы):

Если атрибут name сущности User изменяется, например через стандартный экран управления пользователями, необходимо, чтобы изменялся также и атрибут name связанной сущности Employee. Это обычная задача для "денормализованных" данных, и решается она, как правило, с использованием entity listeners. В данном случае ситуация осложняется тем, что необходимо отслеживать изменения не проектной, а платформенной сущности User, и добавить entity listener с помощью аннотации @Listeners невозможно. Однако, можно добавить listener динамически через бин EntityListenerManager, и сделать это лучше всего на старте приложения.

В результате сразу после старта блока Middleware будет вызван метод initEntityListeners() класса AppLifecycle. В этом методе в качестве entity listener сущности User регистрируется бин sample_UserEntityListener.

Метод onBeforeUpdate() класса UserEntityListener будет вызываться перед каждым сохранением изменений экземпляров User в базу данных. В методе проверяется, есть ли атрибут name среди измененных, и если да, загружается связанный экземпляр Employee, и в нем устанавливается это же значение name.

Присвоение начальных значений атрибутам новых экземпляров сущностей можно производить несколькими способами.

Платформа CUBA поддерживает два типа связи между сущностями: ассоциацию и композицию. В интерфейсе CUBA Studio они названы соответственно ASSOCIATION и COMPOSITION. Ассоциация - это связь между объектами, которые могут существовать отдельно друг от друга. Композиция же используется для связи типа "master-detail" когда экземпляры detail существуют только в составе master. Примером композиции может служить связь аэропорта и терминалов: терминал, не относящийся ни к какому аэропорту, не имеет смысла.

Как правило, редактирование сущностей, входящих в состав композиции, удобно осуществлять совместно. То есть, например, пользователь открывает экран редактирования аэропорта, видит в нем список терминалов, может создавать и редактировать их, но все изменения, как аэропорта, так и терминалов, сохраняются в базу данных вместе в одной транзакции, и только тогда, когда пользователь подтвердит сохранение главной сущности - аэропорта.

В ассоциации many-to-many множество записей в одной таблице может быть связано со множеством записей в другой таблице, при этом первичные ключи обеих связанных сущностей хранятся в отдельной связующей таблице. При необходимости связующая таблица может содержать дополнительные поля.

В зависимости от того, нужны ли вам дополнительные поля в связующей таблице, отношения many-to-many можно реализовать с использованием связующей сущности или без неё. Далее мы рассмотрим оба подхода.

Рассмотрим пример использования наследования сущностей в приложении CUBA.

Рассмотрим типичный случай, когда у заказа могут быть заказчики разных типов - например, юридические и физические лица, или сущности Company и Individual, у которых есть общие атрибуты. Мы хотим хранить общие атрибуты в общей таблице, а специфичные атрибуты для каждого типа - в отдельных связанных таблицах.

Так, в модели данных мы создадим сущность Client как базовый класс, который будем хранить в таблице SAMPLE_CLIENT. Сущности Company и Person будут храниться в отдельных таблицах с внешним ключом, ссылающимся на базовую таблицу.

Сущность Order (заказ) имеет ссылку на сущность Client. Поскольку заказчики могут быть нескольких типов, при создании нового заказа пользователь должен иметь возможность выбрать нужный тип.

Сущность Client.java:

Сущность Company.java:

Сущность: Person.java:

Контроллер экрана OrderEdit.java содержит визуальные компоненты и логику для выбора типа заказчика.

Ниже объясняется, как правильно располагать визуальные компоненты и контейнеры на экранах UI.

Передача параметров из одного экрана в другой является одной из самых частых задач в разработке UI. Рассмотрим типовые решения этой задачи на примере демо-приложения "управление заказами".

Методы, используемые для открытия экранов (openWindow(), openLookup(), openEditor()), позволяют также и возвращать значения из этих экранов.

Сущности, связанные композицией с типом один-к-одному, часто бывает удобно создавать в одном общем экране редактирования. Рассмотрим, как можно реализовать такой экран, на примере отношений сущностей Customer и CustomerDetails.

Теперь обе сущности можно создавать и редактировать в одном экране.

Использование компонента FieldGroup в редакторе сущности не является обязательным. Мы можете легко заменить FieldGroup на отдельные поля, чтобы кастомизировать стандартную разметку экрана.

Ниже приведён пример такого экрана для редактирования сущности Order.

XML-дескриптор экрана order-edit.xml содержит основной источник данных orderDs и вложенный в него orderLinesDs для строк заказа, а также независимый источник данных customersDs, чтобы загружать список покупателей для выбора из выпадающего списка lookupField:

Теперь достаточно создать поля для всех атрибутов сущности Order, указать для каждого поля соответствующий источник данных и нужный атрибут сущности, используя XML-атрибут property:

Такой подход к созданию экранов предоставляет большую гибкость в использовании визуальных компонентов и их расположении на экране.

Данный раздел посвящен использованию визуальных тем в веб-приложениях.

И DataManager и EntityManager предназначены для выполнения операций с сущностями (CRUD). Ниже приведены различия между этими интерфейсами.

DataManager на самом деле делегирует выполнение реализациям DataStore, поэтому особенности DataManager, перечисленные ниже, актуальны только для наиболее часто встречающегося случая, когда вы работаете с сущностями, хранящимися в реляционной базе данных.

При работе на клиентском уровне доступен только DataManager. На среднем слое, используйте EntityManager когда необходимо реализовать атомарную логику внутри транзакции или если его интерфейс лучше подходит для решения задачи. В противном случае, на среднем слое можно использовать любой из интерфейсов на выбор.

Если вам нужно обойти ограничения DataManager при работе на клиентском уровне, создайте свой сервис и используйте EntityManager для работы с данными. В сервисе можно проверять права пользователя с помощью интерфейса Security и возвращать клиенту данные в виде персистентных или неперсистентных сущностей или произвольных значений.

OAuth токен необходим для выполнения любого метода REST API (кроме случая анонимного доступа к REST API). Получить токен можно выполнив POST запрос по адресу

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

Доступ к данному URL защищен с помощью базовой аутентификации с использованием идентификатора и пароля клиента REST API. Обратите внимание, что это не логин и пароль пользователя приложения. Идентификатор и пароль клиента REST API заданы в свойствах приложения cuba.rest.client.id и cuba.rest.client.secret (значения по умолчанию для этих свойств: client и secret). Заголовок Authorization запроса на получение токена должен содержать логин и пароль клиента, разделенные символом ":" и закодированные в base64.

Тип запроса на получение токена должен быть application/x-www-form-urlencoded, кодировка UTF-8.

Запрос должен содержать следующие параметры:

Вы также можете использовать утилиту cURL:

Метод возвращает JSON объект:

Значение токена содержится в поле access_token

Чтобы использовать токен, его нужно передать в заголовке запроса Authorization с типом Bearer, например:

Свойство refresh_token содержит значение refresh токена. Он не может быть использован для доступа к защищённым ресурсам приложения, но он имеет большее время жизни по сравнению с access токеном и используется для получения нового access токена, когда старый токен истек.

Запрос на получение нового access токена с помощью refresh токена должен содержать следующие параметры:

См. также следующие свойства приложения, имеющие отношение к токенам:

Для настройки LDAP аутентификации в REST API используются следующие свойства приложения:

Пример содержимого файла local.app.properties:

Получить OAuth токен можно выполнив POST запрос по адресу:

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

Доступ к данному URL защищен с помощью базовой аутентификации с использованием идентификатора и пароля клиента REST API. Обратите внимание, что это не логин и пароль пользователя приложения. Идентификатор и пароль клиента REST API заданы в свойствах приложения cuba.rest.client.id и cuba.rest.client.secret (значения по умолчанию для этих свойств: client и secret). Заголовок Authorization запроса на получение токена должен содержать логин и пароль клиента, разделенные символом ":" и закодированные в base64.

Запрос должен содержать следующие параметры (соответствуют параметрам стандартной аутентификации):

Тип запроса на получение токена должен быть application/x-www-form-urlencoded, кодировка UTF-8.

Стандартная аутентификация может быть отключена при помощи свойства cuba.rest.standardAuthenticationEnabled:

Различные механизмы аутентификации могут предоставлять токен по ключу, по ссылке, по логину и паролю LDAP и т.д. Стандартный механизм аутентификации в REST API изменить нельзя, но можно создать свой механизм. Для этого необходимо создать REST-контроллер, который предоставит свой URL для входа в приложение.

В этом примере мы рассмотрим механизм аутентификации, позволяющий получить OAuth-токен по промо-коду. За основу возьмём приложение, содержащее сущность Coupon (Купон) с атрибутом code (промо-код). Значение этого атрибута мы будем передавать в качестве параметра аутентификации в GET-запросе.

Предположим, в системе имеется сущность sales$Order, и необходимо получить список экземпляров этой сущности. При этом, необходимо получить не все записи, а 50 записей, начиная с сотой (для отображения третьей странице в каком-либо списке клиентского приложения). Кроме простых атрибутов сущности sales$Order результат должен содержать данные о клиенте (поле customer). Заказы должны быть отсортированы по дате.

Базовый URL для получения списка экземпляров сущности sales$Order:

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

Для выполнения описанных выше условий необходимо задать параметры запроса:

OAuth-токен должен быть передан в заголовке запроса Authorization с типом Bearer:

В итоге получаем следующий GET http-запрос:

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

В cURL запрос может выглядеть так:

Ответ будет выглядеть следующим образом:

Обратите внимание, что для каждой сущности загружаются атрибуты _entityName с именем сущности и _instanceName, содержащий результат вычисления короткого имени для сущности.

Для создания нового экземпляра сущности sales$Order необходимо выполнить POST запрос по адресу:

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

OAuth-токен должен быть передан в заголовке запроса Authorization с типом Bearer.

Тело запроса должно содержать JSON объект, описывающий новый экземпляр, например:

Ниже приведен пример POST запроса для создания нового экземпляра Order в cURL:

В теле запроса передается коллекция позиций заказа items и ссылка на клиента customer. Рассмотрим, как будут обработаны эти атрибуты.

Сначала посмотрим на класс Order:

В сущности Order коллекция items аннотирована @Composition. Методы создания и обновления сущности REST API создают новые экземпляры для всех элементов таких коллекций. Т.е. вместе с заказом (Order) будет создано две позиции заказа (OrderItem).

Ссылка customer не имеет аннотации @Composition, поэтому метод REST API попытается найти клиента с переданным идентификатором и проставить его в поле customer. Если клиент не будет найден, заказ не будет создан и метод вернет ошибку.

В случае успеха возвращается полный граф созданной сущности:

Для изменения экземпляра сущности sales$Order необходимо выполнить PUT запрос по адресу:

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

Последняя часть запроса здесь - это идентификатор изменяемой сущности.

OAuth-токен должен быть передан в заголовке запроса Authorization с типом Bearer.

В теле запроса необходимо передать JSON объект, содержащий только поля, которые мы хотим изменить, например:

В теле ответа будет возвращена измененная сущность:

Перед выполнением запроса с помощью REST API необходимо описать его в конфигурационном файле. В корневом пакете модуля web (например, com.company.sales) необходимо создать файл rest-queries.xml. Затем этот файл объявляется в файле свойств приложения модуля web (web-app.properties):

Содержимое файла rest-queries.xml:

Для выполнения JPQL запроса, необходимо выполнить GET http-запрос к REST API:

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

Части URL:

OAuth-токен должен быть передан в заголовке запроса Authorization с типом Bearer.

Метод возвращает JSON-массив со списком извлеченных экземпляров сущности:

Список других возможных параметров для метода выполнения запросов можно посмотреть в Swagger документации.

JPQL-запрос также может быть выполнен с помощью POST-запроса. Это необходимо для случая, когда параметр JPQL-запроса является коллекцией. В файле конфигурации JPQL-запросов для REST API тип параметра-коллекции должен заканчиваться символами []: java.lang.String[], java.util.UUID[] и т.п.

Параметры JPQL-запроса должны быть переданы в теле HTTP-запроса в JSON map:

URL POST-запроса:

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

Предположим, в системе имеется сервис OrderService, реализация которого выглядит следующим образом:

Перед выполнением метода сервиса с помощью REST API необходимо разрешить его вызов в конфигурационном файле. В корневом пакете модуля web (например, com.company.sales) необходимо создать файл rest-services.xml. Затем этот файл объявляется в файле свойств приложения модуля web (web-app.properties):

Содержимое файла rest-services.xml:

Для вызова метода сервиса, необходимо выполнить GET http-запрос к REST API вида:

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

Части URL:

OAuth-токен должен быть передан в заголовке запроса Authorization с типом Bearer.

Метод сервиса может вернуть как простой тип данных, так и сущность, коллекцию сущностей или произвольный POJO. В нашем случае метод возвращает BigDecimal, поэтому в теле ответа нам вернется число:

REST API позволяет выполнять методы сервисов, аргументами которых являются не только простые типы, но также:

Небольшой пример. Предположим, в сервис OrderService, созданный в предыдущем разделе, добавлен следующий метод:

Класс OrderValidationResult выглядит следующим образом:

Новый метод сервиса принимает сущность Order в качестве первого аргумента и возвращает POJO.

Перед вызовом данного метода с помощью REST API необходимо разрешить его, добавив запись в конфигурационный файл rest-services.xml (его создание было рассмотрено в Вызов метода сервиса (GET)):

Метод validateOrder сервиса вызывается POST запросом по адресу:

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

Параметры в случае POST передаются в теле запроса в JSON объекте. Каждое поле JSON объекта соответствует аргументу метода сервиса:

OAuth-токен должен быть передан в заголовке запроса Authorization с типом Bearer.

Метод вернет сериализованный POJO:

При скачивании файла передавать токен в заголовке запроса часто оказывается неудобно. Хочется иметь URL для скачивания, который можно подставить например в атрибут src тега img. В этом случае передача <<OAuth-токена возможна в самом запросе в параметре с именем access_token.

Например, в систему загружено изображение. Идентификатор соответствующего FileDescriptor - 44809679-e81c-e5ae-dd81-f56f223761d6.

В этом случае URL для загрузки изображения будет выглядеть так:

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

Для загрузки файлов вам нужно получить OAuth-токен, который понадобится в дальнейших запросах.

Используем простую форму для загрузки:

Далее используем jQuery, чтобы получить JSON с объектом data, который, по сути, представляет собой новый FileDescriptor. Использовать загруженный файл мы можем по идентификатору созданного экземпляра FileDescriptor с токеном в качестве параметра:

В данном разделе приведен пример использования REST API v2 из JavaScript, выполняющегося на HTML-странице. На странице изначально отображается форма логина, а после успешного входа - соответствующее сообщение и список сущностей.

Для простоты, в данном примере для хранения файлов HTML/CSS/JavaScript используется каталог modules/web/web/VAADIN, так как соответствующий каталог развернутого веб-приложения используется для выдачи статических ресурсов. Поэтому никаких настроек на сервере Tomcat делать не требуется. Результирующий URL будет начинаться с http://localhost:8080/app/VAADIN, так что данный вариант не стоит использовать в реальном приложении, вместо этого создайте отдельное веб-приложение со своим контекстом.

Загрузите jQuery и Bootstrap и скопируйте в каталог modules/web/web/VAADIN вашего проекта. Создайте файлы customers.html и customers.js, так что содержимое каталога должно быть примерно таким:

Содержимое файла customers.html: