Свернуть все | Развернуть все | Скрыть панель

Содержание

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

Версия 5.6    Более новая версия доступна в разделе документации.


Содержание

Предисловие
1. Введение
1.1. Обзор платформы
1.2. Технические требования
1.3. Release Notes
2. Установка и настройка инструментария
2.1. Установка CUBA Studio
2.2. Интеграция CUBA Studio с IDE
3. Быстрый старт
3.1. Описание задачи
3.2. Создание проекта
3.3. Создание сущностей
3.4. Создание таблиц базы данных
3.5. Создание экранов пользовательского интерфейса
3.5.1. Экраны управления Покупателями
3.5.2. Экраны управления Заказами
3.5.3. Меню приложения
3.5.4. Экран редактирования Покупателя со списком Заказов
3.6. Запуск приложения
4. Устройство платформы
4.1. Архитектура
4.1.1. Уровни и блоки приложения
4.1.2. Модули приложения
4.1.3. Базовые проекты
4.1.4. Состав приложения
4.2. Общие компоненты
4.2.1. Модель данных
4.2.1.1. Базовые классы сущностей
4.2.1.2. Аннотации сущностей
4.2.1.2.1. Аннотации класса
4.2.1.2.2. Аннотации атрибутов
4.2.1.3. Атрибуты типа enum
4.2.1.4. Мягкое удаление
4.2.1.4.1. Использование
4.2.1.4.2. Политика обработки связей
4.2.1.4.3. Ограничение уникальности на уровне БД
4.2.2. Metadata Framework
4.2.2.1. Интерфейсы метаданных
4.2.2.2. Формирование метаданных
4.2.2.3. Datatype
4.2.2.3.1. Пример форматирования даты в UI
4.2.2.3.2. Примеры форматирования дат и чисел в коде приложения
4.2.2.3.3. Пример специализированного Datatype
4.2.2.4. Мета-аннотации
4.2.3. Представления
4.2.3.1. Создание представлений
4.2.4. Управляемые бины
4.2.4.1. Создание бина
4.2.4.2. Использование бина
4.2.5. JMX-бины
4.2.5.1. Создание JMX-бина
4.2.5.2. JMX-бины платформы
4.2.5.2.1. CachingFacadeMBean
4.2.5.2.2. ConfigStorageMBean
4.2.5.2.3. EmailerMBean
4.2.5.2.4. PersistenceManagerMBean
4.2.5.2.5. ScriptingManagerMBean
4.2.5.2.6. ServerInfoMBean
4.2.6. Интерфейсы инфраструктуры
4.2.6.1. Configuration
4.2.6.2. Messages
4.2.6.2.1. MessageTools
4.2.6.3. Metadata
4.2.6.3.1. MetadataTools
4.2.6.4. Resources
4.2.6.5. Scripting
4.2.6.6. Security
4.2.6.7. TimeSource
4.2.6.8. UserSessionSource
4.2.6.9. UuidSource
4.2.6.10. DataManager
4.2.6.10.1. Запросы с distinct
4.2.6.10.2. Последовательная выборка
4.2.7. AppContext
4.2.8. Свойства приложения
4.2.8.1. Доступ к свойствам
4.2.8.2. Хранение свойств в файлах
4.2.8.3. Хранение свойств в базе данных
4.2.8.4. Конфигурационные интерфейсы
4.2.8.4.1. Использование
4.2.8.4.2. Типы свойств
4.2.8.4.3. Значения по умолчанию
4.2.9. Локализация сообщений
4.2.9.1. Пакеты сообщений
4.2.9.2. Главный пакет сообщений
4.2.9.3. Локализация названий сущностей и атрибутов
4.2.9.4. Локализация enum
4.2.10. Аутентификация пользователей
4.2.10.1. UserSession
4.2.10.2. Вход в систему
4.2.10.3. SecurityContext
4.2.11. Обработка исключений
4.2.11.1. Классы исключений
4.2.11.2. Передача исключений Middleware
4.2.11.3. Обработчики исключений клиентского уровня
4.3. Компоненты работы с базой данных
4.3.1. Типы СУБД
4.3.1.1. Поддержка произвольных СУБД
4.3.1.2. Версия СУБД
4.3.2. Скрипты создания и обновления БД
4.3.2.1. Структура SQL-скриптов
4.3.2.2. Структура Groovy-скриптов
4.3.3. Выполнение скриптов БД задачами Gradle
4.3.4. Выполнение скриптов БД сервером
4.4. Компоненты среднего слоя
4.4.1. Сервисы
4.4.1.1. Создание сервиса
4.4.1.2. Использование сервиса
4.4.1.3. DataService
4.4.2. Системная аутентификация
4.4.3. Интерфейс Persistence
4.4.3.1. PersistenceTools
4.4.3.2. PersistenceHelper
4.4.3.3. DbTypeConverter
4.4.4. Слой ORM
4.4.4.1. EntityManager
4.4.4.2. Состояния сущности
4.4.4.3. Загрузка по требованию
4.4.4.4. Выполнение JPQL запросов
4.4.4.4.1. Поиск подстроки без учета регистра
4.4.4.4.2. Макросы в JPQL
4.4.4.5. Выполнение SQL запросов
4.4.4.6. Entity Listeners
4.4.5. Управление транзакциями
4.4.5.1. Программное управление транзакциями
4.4.5.2. Декларативное управление транзакциями
4.4.5.3. Примеры взаимодействия транзакций
4.4.5.3.1. Откат вложенной транзакции
4.4.5.3.2. Чтение и изменение данных во вложенной транзакции
4.4.5.4. Таймаут транзакции
4.4.5.4.1. Особенности реализации для различных СУБД
4.5. Универсальный пользовательский интерфейс
4.5.1. Экраны
4.5.1.1. Типы экранов
4.5.1.1.1. Фрейм
4.5.1.1.2. Простой экран
4.5.1.1.3. Экран выбора
4.5.1.1.4. Экран редактирования
4.5.1.2. XML-дескриптор
4.5.1.3. Контроллер экрана
4.5.1.3.1. AbstractFrame
4.5.1.3.2. AbstractWindow
4.5.1.3.3. AbstractLookup
4.5.1.3.4. AbstractEditor
4.5.1.3.5. Инжекция зависимостей контроллеров
4.5.1.3.6. Компаньоны контроллеров
4.5.2. Библиотека визуальных компонентов
4.5.2.1. Компоненты
4.5.2.1.1. Button
4.5.2.1.2. Bulk Editor
4.5.2.1.3. CheckBox
4.5.2.1.4. DateField
4.5.2.1.5. Embedded
4.5.2.1.6. FieldGroup
4.5.2.1.7. FileMultiUploadField
4.5.2.1.8. FileUploadField
4.5.2.1.9. Filter
4.5.2.1.9.1. Использование фильтра
4.5.2.1.9.2. Описание компонента Filter
4.5.2.1.9.3. Права пользователей
4.5.2.1.9.4. Внешние параметры для управления фильтрами
4.5.2.1.9.5. Последовательное наложение фильтров
4.5.2.1.10. GroupTable
4.5.2.1.11. Label
4.5.2.1.12. Link
4.5.2.1.13. LinkButton
4.5.2.1.14. LookupField
4.5.2.1.15. LookupPickerField
4.5.2.1.16. MaskedField
4.5.2.1.17. OptionsGroup
4.5.2.1.18. PasswordField
4.5.2.1.19. PickerField
4.5.2.1.20. PopupButton
4.5.2.1.21. ProgressBar
4.5.2.1.22. Related Entities
4.5.2.1.23. RichTextArea
4.5.2.1.24. SearchPickerField
4.5.2.1.25. Table
4.5.2.1.26. TextArea
4.5.2.1.27. TextField
4.5.2.1.28. TimeField
4.5.2.1.29. TokenList
4.5.2.1.30. Tree
4.5.2.1.31. TreeTable
4.5.2.1.32. TwinColumn
4.5.2.2. Контейнеры
4.5.2.2.1. BoxLayout
4.5.2.2.2. ButtonsPanel
4.5.2.2.3. GridLayout
4.5.2.2.4. GroupBoxLayout
4.5.2.2.5. IFrame
4.5.2.2.6. ScrollBoxLayout
4.5.2.2.7. SplitPanel
4.5.2.2.8. TabSheet
4.5.2.3. Разное
4.5.2.3.1. Formatter
4.5.2.3.2. Presentation
4.5.2.3.3. Timer
4.5.2.3.4. Validator
4.5.2.4. XML-атрибуты компонентов
4.5.3. Источники данных
4.5.3.1. Создание источников данных
4.5.3.1.1. Декларативное создание
4.5.3.1.2. Программное создание
4.5.3.1.3. Собственные классы реализации
4.5.3.2. Запросы в CollectionDatasourceImpl
4.5.3.2.1. Возвращаемые значения
4.5.3.2.2. Параметры запроса
4.5.3.2.3. Фильтр запроса
4.5.3.2.4. Поиск подстроки без учета регистра
4.5.3.3. Слушатели источников данных
4.5.3.4. DsContext
4.5.3.5. DataSupplier
4.5.4. Действия. Интерфейс Action
4.5.4.1. Декларативное создание действий
4.5.4.2. Стандартные действия
4.5.4.2.1. Стандартные действия с коллекцией
4.5.4.2.1.1. CreateAction
4.5.4.2.1.2. EditAction
4.5.4.2.1.3. RemoveAction
4.5.4.2.1.4. RefreshAction
4.5.4.2.1.5. AddAction
4.5.4.2.1.6. ExcludeAction
4.5.4.2.1.7. ExcelAction
4.5.4.2.2. Стандартные действия поля выбора
4.5.4.2.2.1. LookupAction
4.5.4.2.2.2. ClearAction
4.5.4.2.2.3. OpenAction
4.5.4.3. BaseAction
4.5.5. Диалоговые окна и уведомления
4.5.5.1. Диалоговые окна
4.5.5.2. Уведомления
4.5.6. Фоновые задачи
4.5.6.1. Использование фоновых задач
4.5.6.2. Настройка окружения
4.5.7. Создание темы приложения
4.5.7.1. Тема в веб-приложениях
4.5.7.1.1. Использование существующих тем
4.5.7.1.2. Расширение существующей темы
4.5.7.1.3. Создание новой темы
4.5.7.2. Тема в десктоп-приложениях
4.5.8. Специфика Web Client
4.5.8.1. Работа с компонентами Vaadin
4.5.8.2. Компоновка главного окна приложения
4.5.9. Специфика Desktop Client
4.5.9.1. Работа с компонентами Swing
4.5.10. Создание собственных компонентов
4.5.10.1. Использование сторонних компонентов Vaadin
4.5.10.2. Интеграция компонентов в Generic UI
4.5.11. Горячие клавиши
4.6. Компоненты портала
4.6.1. Базовая функциональность
4.6.2. REST API
4.6.2.1. Включение в проект
4.6.2.2. Описание функций
4.6.2.2.1. Логин
4.6.2.2.2. Логаут
4.6.2.2.3. Загрузка экземпляра персистентного объекта из базы данных по идентификатору
4.6.2.2.4. Выполнение JPQL запроса для выборки данных
4.6.2.2.5. Коммит новых и измененных экземпляров, удаление
4.6.2.2.6. Загрузка файла из хранилища
4.6.2.2.7. Получение описания модели данных в формате HTML
4.6.2.2.8. Cоздание новых представлений на сервере
4.6.2.2.9. Вызов сервисов
4.6.2.2.9.1. Вызов сервиса с помощью GET запроса
4.6.2.2.9.2. Вызов сервиса с помощью POST запроса
4.6.2.2.9.3. Поддерживаемые типы параметров метода сервиса
4.6.2.2.9.4. Результат вызова сервиса
4.7. Механизмы платформы
4.7.1. Выполнение задач по расписанию
4.7.1.1. Spring TaskScheduler
4.7.1.2. Назначенные задания CUBA
4.7.1.2.1. Регистрация задания
4.7.1.2.2. Управление обработкой заданий
4.7.1.2.3. Особенности реализации
4.7.2. Отправка email
4.7.2.1. Методы отправки
4.7.2.2. Вложения
4.7.2.3. Настройка параметров отправки email
4.7.3. Динамические атрибуты
4.7.3.1. Управление динамическими атрибутами
4.7.3.2. Категоризируемые сущности
4.7.3.3. Динамические атрибуты в REST API
4.7.4. Пессимистичная блокировка
4.7.4.1. Блокировка редактирования сущностей
4.7.4.2. Блокировка произвольных процессов
4.7.4.3. Мониторинг блокировок
4.7.5. Статистика сущностей
4.7.6. Журнал изменений сущностей
4.7.6.1. Настройка журналирования
4.7.6.2. Отображение журнала
4.7.7. Снимки сущностей
4.7.7.1. Сохранение снимков
4.7.7.2. Отображение снимков
4.7.8. Хранилище файлов
4.7.8.1. Загрузка файлов
4.7.8.2. Выгрузка данных
4.7.8.3. Стандартная реализация хранилища
4.7.9. Генерация последовательностей
4.7.10. Выполнение SQL с помощью QueryRunner
4.7.11. Интеграция с MyBatis
4.7.12. Панель папок
4.7.12.1. Папки приложения
4.7.12.2. Папки поиска
4.7.12.3. Наборы
4.7.13. Ссылки на экраны
4.7.14. Инспектор сущностей
4.7.15. Информация об используемом ПО
4.8. Расширение функциональности
4.8.1. Расширение сущности
4.8.2. Расширение экранов
4.8.3. Расширение бизнес-логики
5. Разработка приложений
5.1. Рекомендуемый стиль кода
5.2. Файловая структура проекта
5.3. Описание скриптов сборки
5.3.1. Структура build.gradle
5.3.2. Запуск задач сборки
5.3.3. Сборка на сервере Continuous Integration
5.4. Создание проекта
5.5. Проектирование БД
5.5.1. Создание схемы БД
5.5.2. Подключение к HSQLDB внешними инструментами
5.5.2.1. Подключение с помощью Squirrel SQL
5.5.2.2. Подключение с помощью IntelliJ IDEA Ultimate
5.5.3. Особенности PostgreSQL
5.5.4. Особенности MS SQL Server
5.5.5. Особенности Oracle Database
5.6. Логгирование
5.6.1. Настройка логгирования в Tomcat
5.6.2. Настройка логгирования в десктоп клиенте
5.7. Отладка и тестирование
5.7.1. Подключение отладчика
5.7.2. Отладка виджетов в веб-браузере
5.7.3. Тестирование
5.7.3.1. Модульные тесты
5.7.3.2. Интеграционные тесты Middleware
5.7.3.3. Интеграционные тесты клиентского уровня
5.8. Рецепты разработки
5.8.1. Получение локализованных сообщений
5.8.2. Присвоение начальных значений
5.8.2.1. Инициализация полей сущности
5.8.2.2. Инициализация с помощью CreateAction
5.8.2.3. Использование метода initNewItem
5.8.3. Редактирование композитных сущностей
5.8.3.1. Реализация композиции
5.8.3.2. Глубокая композиция
5.8.4. Выполнение кода на старте приложения
5.8.5. Загрузка и вывод изображений
5.8.6. Создание собственных визуальных компонентов
5.8.6.1. Пример использования стороннего компонента Vaadin
5.8.6.2. Пример интеграции компонента Vaadin в Generic UI
6. Развертывание приложений
6.1. Каталоги приложения
6.1.1. Конфигурационный каталог
6.1.2. Рабочий каталог
6.1.3. Каталог журналов
6.1.4. Временный каталог
6.1.5. Каталог скриптов базы данных
6.2. Варианты развертывания
6.2.1. Быстрое развертывание в Tomcat
6.2.1.1. Использование Tomcat при эксплуатации приложения
6.2.2. Развертывание в WAR
6.3. Масштабирование приложения
6.3.1. Настройка кластера Web Client
6.3.1.1. Установка и настройка Load Balancer
6.3.1.2. Настройка серверов Web Client
6.3.2. Настройка кластера Middleware
6.3.2.1. Настройка обращения к кластеру Middleware
6.3.2.2. Настройка взаимодействия серверов Middleware
6.3.3. Server Id
6.4. Использование инструментов JMX
6.4.1. Встроенная JMX консоль
6.4.2. Настройка удаленного доступа к JMX
6.4.2.1. Tomcat JMX под Windows
6.4.2.2. Tomcat JMX под Linux
6.5. Создание и обновление БД при эксплуатации приложения
6.5.1. Использование механизма выполнения скриптов БД сервером
6.5.2. Инициализация и обновление БД из командной строки
6.6. Использование файла лицензии
7. Подсистема безопасности
7.1. Компоненты подсистемы безопасности
7.1.1. Окно входа в систему
7.1.2. Пользователи
7.1.2.1. Замещение пользователей
7.1.3. Часовой пояс
7.1.4. Разрешения
7.1.5. Роли
7.1.6. Группы доступа
7.1.6.1. Ограничения
7.1.6.2. Атрибуты сессии
7.1.7. Интеграция с LDAP
7.1.7.1. Базовая интеграция с Active Directory
7.1.7.2. Настройка аутентификации с использованием Jespa
7.1.7.2.1. Подключение библиотеки
7.1.7.2.2. Настройка конфигурации
7.2. Примеры управления доступом
7.2.1. Настройка ролей
7.2.2. Создание локальных администраторов
A. Конфигурационные файлы
A.1. context.xml
A.2. datatypes.xml
A.3. dispatcher-spring.xml
A.4. menu.xml
A.5. metadata.xml
A.6. permissions.xml
A.7. persistence.xml
A.8. remoting-spring.xml
A.9. screens.xml
A.10. spring.xml
A.11. views.xml
A.12. web.xml
B. Свойства приложения
C. Системные свойства
Основные определения и понятия

Предисловие

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

1. Целевая аудитория

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

  • Java Standard Edition

  • Реляционные базы данных (SQL, DDL)

2. Дополнительные материалы

Настоящее Руководство, а также другая документация по платформе CUBA, доступны по адресу www.cuba-platform.ru/manual.

Для глубокого понимания принципов работы платформы полезным является знакомство со следующими технологиями и фреймворками:

3. Обратная связь

Если у Вас имеются предложения по улучшению данного руководства, обратитесь пожалуйста в службу поддержки по адресу ru.cuba-platform.com/support/topics.

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

Глава 1. Введение

В данной главе приводятся сведения о назначении и возможностях платформы CUBA.

1.1. Обзор платформы

Ключевые особенности

  • Использование платформы Java, а, следовательно, возможность работы под управлением практически любых операционных систем на серверах и рабочих станциях

  • Полностью открытый исходный код

  • Независимость от специфики СУБД

  • Создаваемые на базе платформы приложения легко могут быть развернуты в отказоустойчивой конфигурации

  • Наличие эффективных средств разработки пользовательского интерфейса с помощью только Java и XML

  • Мощные средства разграничения прав доступа пользователей к информации с возможностью настройки в работающем приложении (см. руководство Подсистема безопасности)

  • Встроенный механизм создания и генерации отчетов с выводом в форматы офисных документов и PDF (см. руководство Генератор отчетов)

  • Механизм создания и выполнения бизнес-процессов с интегрированным визуальным редактором процессов (см. руководство Подсистема Workflow)

  • Полнотекстовый поиск по атрибутам сущностей и по содержимому загруженных файлов (см. руководство Полнотекстовый поиск)

  • Возможность отображения диаграмм, в том числе, диаграммы Ганта (см. руководство Отображение диаграмм)

  • Встроенный REST API с передачей данных в форматах XML или JSON для быстрой интеграции со сторонними приложениями

  • Механизм создания расширений функциональности, позволяющий адаптировать тиражируемые продукты для конкретных заказчиков, не затрудняя при этом обновления версий продуктов

  • CUBA Studio - инструмент быстрой разработки на платформе. Studio включает в себя средства создания нового проекта, описания модели данных, визуальный редактор экранов и других элементов проекта. Использование Studio не исключает возможности программирования в классической Java IDE, тем самым достигается максимальная эффективность при работе над проектом с помощью обоих инструментов:

    • Studio используется для быстрого старта проекта, визуального создания модели данных и компоновки экранов UI

    • Java IDE используется для программирования бизнес-логики и обработки событий UI

    CUBA Studio содержит средства для взаимодействия с IntelliJ IDEA и Eclipse, позволяющие быстро переходить из Studio в IDE и обратно.

Преимущества использования платформы CUBA

  • Система, строящаяся на платформе, приобретает эффективную архитектуру, опробованную на множестве приложений, созданных компанией Haulmont и другими разработчиками

  • Декларативный подход к созданию пользовательского интерфейса имеет следующие преимущества:

    • абстрагирует разработчика от сложностей разнородных технологий (HTML/JavaScript, Swing, и т.п.)

    • четко разделяет визуальное расположение и логику инициализации и реакции на события, облегчая понимание и изменение кода

  • Созданные таким образом экраны одинаково работоспособны в обоих типах клиентов, поддерживаемых платформой: веб и десктоп, что позволяет с минимумом усилий создавать системы, использующие преимущества веб-интерфейса и/или настольных приложений

  • Платформой предоставляется готовая функциональность на следующих уровнях:

  • Функциональность платформы позволяет значительно сократить сроки разработки и удешевить проект

  • Для создания веб-клиента приложения на основе CUBA не обязательно хорошее знание классических веб-технологий: HTML, CSS, JavaScript

1.2. Технические требования

Минимальные требования для ведения разработки на платформе CUBA:

  • Оперативная память - 4 ГБ.

  • Место на жестком диске - 5 ГБ.

  • Операционная система - Microsoft Windows, Linux или Mac OS X.

1.3. Release Notes

Список изменений в платформе доступен по адресу files.cuba-platform.com/cuba/platform/platform-5.5-changelog.html.

Глава 2. Установка и настройка инструментария

Минимально необходимым набором программного обеспечения является:

  • Java SE Development Kit (JDK) 7 или 8. Рекомендуется использовать Oracle Java HotSpot VM.

    Для сборки и запуска проектов вне Studio в переменной окружения JAVA_HOME необходимо установить путь к корневому каталогу JDK, например C:\Program Files\Java\jdk1.8.0_45. Для Windows это можно сделать, открыв Компьютер -> Свойства системы -> Дополнительные параметры системы -> Дополнительно -> Переменные среды, и задав значение переменной в списке Системные переменные.

  • Cреда разработки на Java: IntelliJ IDEA Community Edition 12+ или Eclipse 4.3+. Рекомендуется использовать IntelliJ IDEA.

В простейшем случае в качестве сервера баз данных приложений используется встроенный HyperSQL (http://hsqldb.org), что вполне подходит для исследования возможностей платформы и прототипирования приложений. Для создания реальных приложений рекомендуется установить и использовать в проекте какую-либо из полноценных СУБД, поддерживаемых платформой, например PostgreSQL.

Веб-интерфейс приложений, создаваемых на основе платформы, поддерживает все популярные современные браузеры, в том числе Google Chrome, Mozilla Firefox, Safari, Opera 15+, Internet Explorer 8+.

2.1. Установка CUBA Studio

Окружение:

  • Убедитесь в наличии на компьютере Java SE Development Kit (JDK) 7 или 8, выполнив в консоли команду

    java -version

    В ответ должно быть выведено сообщение с номером версии Java, например 1.8.0_45.

  • Если для соединения с интернетом используется прокси-сервер, в JVM, исполняющие Studio и Gradle, необходимо передавать специальные системные свойства Java. Они описаны в документе http://docs.oracle.com/javase/7/docs/technotes/guides/net/proxies.html (см. свойства для протоколов HTTP и HTTPS).

    Рекомендуется установить нужные свойства в переменной окружения JAVA_OPTS. Скрипт запуска Studio передает JAVA_OPTS в java.exe.

Для установки Studio выполните следующий шаги:

  1. Загрузите архив studio-<version>.zip со страницы www.cuba-platform.ru/download.

  2. Распакуйте архив в локальный каталог, например, c:/work/studio

  3. Откройте командную строку, перейдите в подкаталог bin и запустите

    studio

  4. В окне CUBA Studio Server введите следующие параметры:

    • Java home − JDK, который будет использоваться для сборки и запуска проектов. Если вы установили переменную окружения JAVA_HOME как описано в начале данной главы, ее значение будет подставлено в данное поле. В противном случае Studio попытается самостоятельно найти каталог установки Java.

    • Gradle home − оставьте поле пустым, в этом случае при первом запуске будет автоматически загружен нужный дистрибутив Gradle.

      Если по какой-либо причине Вы хотите использовать уже установленный на компьютере Gradle, введите в поле путь к соответствующему каталогу. Для работы системы сборки проектов требуется Gradle версии 1.12.

    • Server port − порт, на котором будет запущен сервер CUBA Studio (по умолчанию 8111)

    • IDE port − порт, на котором принимает подключения плагин IDE (по умолчанию 48561)

    • Repository − URL и параметры аутентификации репозитория бинарных артефактов.

    Также доступны следующие опции:

    • Check for updates - проверять наличие новых версий при старте.

    • Help language - язык встроенной справки.

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

    • Send anonymous statistics and crash reports - разрешить Studio отправлять статистику ошибок разработчикам.

    • Enable remote connection - по умолчанию считается, что Studio работает на локальном хосте. Установите флажок, если вам нужна возможность подкючения к этой копии Studio с удаленного хоста.

  5. Запустите сервер Studio, нажав кнопку Start.

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

    Затем запустится веб-сервер, и в поле URL отобразится адрес, по которому доступен интерфейс Studio. Нажав ->, можно открыть веб-браузер, нажав Copy, − скопировать адрес в буфер обмена.

  6. Запустите веб-браузер и перейдите по указанному адресу.

  7. В веб-интерфейсе Studio нажмите кнопку Open project. В открывшемся окне Select project нажмите New для создания нового проекта, или Import для добавления имеющегося проекта в список Studio.

  8. Сразу после открытия проекта Studio загружает исходный код базовых проектов платформы, на которых основан проект, и сохраняет его в локальном каталоге. Перед сборкой приложения рекомендуется дождаться окончания загрузки и убедиться в том, что индикатор фоновых задач в левом нижнем углу экрана Studio погас.

2.2. Интеграция CUBA Studio с IDE

Для интеграции с IntelliJ IDEA или Eclipse выполните следующие шаги:

  1. Откройте или создайте новый проект в Studio

  2. Перейдите в секцию Project properties и нажмите кнопку Edit. Выберите нужную Java IDE флажками IntelliJ IDEA или Eclipse.

  3. В главном меню Studio выберите пункт меню Build > Create or update <IDE> project files. В каталоге проекта будут созданы соответствующие файлы

  4. Для интеграции с IntelliJ IDEA 12:

    1. Запустите IntelliJ IDEA 12 и установите плагин CUBA Framework Integration, доступный в репозитории плагинов: File > Settings > Plugins > Browse Repositories.

    2. В IntelliJ IDEA в меню Settings в группе Languages and Frameworks найдите пункт CUBA. На панели Studio integration установите флажок Enabled и нажмите на кнопку OK.

  5. Для интеграции с Eclipse 4.3:

    1. Запустите Eclipse, откройте Help > Install New Software, добавьте репозиторий http://files.cuba-platform.com/eclipse-update-site и установите плагин CUBA Plugin.

    2. В Eclipse в меню Window > Preferences в секции CUBA установите флажок Studio Integration Enabled и нажмите на кнопку OK.

Обратите внимание, что в панели статуса Studio загорелась надпись IDE: on port 48561. Теперь при нажатии кнопок IDE в Studio соответствующие файлы исходных кодов будут открываться редактором IDE.

Глава 3. Быстрый старт

В данном разделе рассматривается создание приложения при помощи CUBA Studio. Эта же информация изложена в видеороликах, доступных по адресу www.cuba-platform.ru/quickstart.

На Вашей рабочей машине уже должно быть установлено и настроено необходимое программное обеспечение, см. Глава 2, Установка и настройка инструментария.

Основные задачи, стоящие при разработке нашего приложения:

  1. Разработка модели данных, которая заключается в создании сущностей предметной области и соответствующих таблиц базы данных.

  2. Разработка экранов пользовательского интерфейса, позволяющих создавать, просматривать, обновлять и удалять сущности модели данных.

3.1. Описание задачи

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

Покупатель имеет следующие характеристики:

  • Имя

  • Электронная почта

Характеристики заказа:

  • Принадлежность покупателю

  • Дата

  • Сумма

Пользовательский интерфейс приложения должен содержать:

  • Окно списка покупателей;

  • Окно редактирования сведений о покупателе, содержащее также список заказов данного покупателя;

  • Окно общего списка заказов;

  • Окно редактирования заказа.

Приложение должно поддерживать русский и английский язык интерфейса.

3.2. Создание проекта

  1. Запустите CUBA Studio и откройте ее веб-интерфейс (см. Раздел 2.1, «Установка CUBA Studio»).

  2. В стартовом окне нажмите на кнопку Open project.

  3. В отобразившемся окне Select project нажмите на кнопку New.

  4. В окне New project в поле Project name введите имя проекта - sales. Имя должно содержать только латинские буквы, цифры и знак подчеркивания. Тщательно продумайте имя проекта на данном этапе, так как в дальнейшем его невозможно изменить без сложного ручного вмешательства.

  5. В полях ниже автоматически сгенерируются:

    • Project path − путь к каталогу нового проекта. Каталог можно выбрать вручную, нажав на кнопку ... рядом с полем. Отобразится окно Folder select со списком папок на жестком диске. Вы можете выбрать одну из них или создать новый каталог, нажав на кнопку +.

    • Project namespace - пространство имен, которое будет использоваться как префикс имен сущностей и таблиц базы данных. Пространство имен может состоять только из латинских букв, и должно быть как можно короче. Например, если имя проекта - sales_2, то пространство имен может быть sales или sal.

    • Root package − корневой пакет Java-классов. Может быть скорректирован позже, однако сгенерированные на этапе создания классы перемещены не будут.

    • Base projects version - используемая в проекте версия платформы. Артефакты платформы будут автоматически загружены из репозитория при сборке проекта.

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

  6. Нажмите на кнопку OK. В указанном каталоге sales будет создан пустой проект, и откроется главное окно Studio.

  7. Сборка проекта. Выберите пункт главного меню Studio Build > Assemble project. На этом этапе будут загружены все необходимые библиотеки и в подкаталогах build модулей будут собраны артефакты проекта.

  8. Создание базы данных на локальном сервере HyperSQL. Выберите пункт меню Run > Create database. Имя БД по умолчанию совпадает с пространством имен проекта.

  9. Выберите пункт меню Run > Deploy. В подкаталоге build проекта будет установлен сервер Tomcat с собранным приложением.

  10. Выберите пункт меню Run > Start application server. Через несколько секунд в панели статуса ссылка рядом с надписью Web application станет доступной, и по ней можно осуществить переход к приложению непосредственно из Studio.

    Логин и пароль пользователя − admin / admin.

    Запущенное приложение содержит два главных пункта меню (Администрирование и Помощь), функциональность подсистемы безопасности и администрирования системы.

3.3. Создание сущностей

Создадим класс сущности Покупатель (Customer).

  • Перейдите на вкладку Entities на панели навигатора и нажмите на кнопку New entity. Появится диалоговое окно New entity.

  • В поле Class name введите название класса сущности − Customer.

  • Нажмите OK. В рабочей области откроется страница дизайнера сущности.

  • В полях Name и Table автоматически сгенерируются имя сущности и имя таблицы в базе данных.

  • В поле Parent class оставьте установленное значение − StandardEntity.

  • Поле Inheritance strategy оставьте пустым.

  • Нажмите на кнопку рядом с полем Name. На экране отобразится окно Localized message, в нем следует задать локализацию имени сущности на доступных языках.

Далее создадим атрибуты сущности. Для этого нажмите на кнопку New, находящуюся под таблицей Attributes.

  • В отобразившемся окне Create attribute в поле Name введите название атрибута сущности − name, в списке Attribute type выберите значение DATATYPE, в поле Type укажите тип атрибута String и далее укажите длину текстового атрибута в поле Length, равной 100 символам. Установите флажок Mandatory. В поле Column автоматически сгенерируется имя колонки таблицы в базе данных.

    Далее нажмите на кнопку рядом с названием атрибута. На экране отобразится окно Localized message, в нем следует задать локализацию названия атрибута на доступных языках.

    Для добавления атрибута нажмите на кнопку Add.

  • Атрибут email создается таким же образом, за исключением того, что в поле Length следует указать значение 50.

После создания атрибутов перейдите на вкладку Instance name дизайнера сущности для задания Name pattern. В списке Available attributes выделите атрибут name и перенесите его в список Name pattern attributes нажав на кнопку с изображением стрелки вправо.

На этом создание сущности Customer завершено. Нажмите на кнопку OK в верхнем левом углу дизайнера сущности для сохранения изменений.

Создадим сущность Заказ (Order). В панели Entities нажмите на кнопку New entity. В поле Class name введите название класса сущности − Order. Сущность должна иметь следующие атрибуты:

  • Namecustomer, Attribute typeASSOCIATION, TypeCustomer, CardinalityMANY_TO_ONE.

  • Namedate, Attribute typeDATATYPE, TypeDate. Для атрибута date установите флажок Mandatory.

  • Nameamount, Attribute typeDATATYPE, TypeBigDecimal.

Для каждого атрибута укажите локализованные названия нажимая на кнопку рядом с именем атрибута.

3.4. Создание таблиц базы данных

Для создания таблиц базы данных достаточно на вкладке Entities панели навигатора нажать на кнопку Generate DB scripts. После этого откроется страница Database scripts. На вкладке будут сгенерированы скрипты обновления базы данных от ее текущего состояния (Update scripts) и скрипты создания базы данных с нуля (Init tables, Init constraints, Init data). Также на вкладке будут доступны уже выполненные скрипты обновления базы данных, если они есть.

Чтобы сохранить сгенерированные скрипты, нажмите на кнопку Save and close. Для запуска скриптов обновления остановите запущенное приложение с помощью команды Run > Stop application server, затем выполните Run > Update database.

3.5. Создание экранов пользовательского интерфейса

Создадим экраны приложения, позволяющие управлять информацией о Покупателях и Заказах.

3.5.1. Экраны управления Покупателями

Для создания стандартных экранов просмотра и редактирования Покупателей необходимо выделить сущность Customer на вкладке Entities панели навигатора и нажать на кнопку Create standard screens внизу панели. После этого на экране отобразится окно Create standard screens.

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

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

Для экранов можно задать локализацию заголовков. Для этого выделите один из файлов и нажмите на кнопку Edit. Отобразится страница дизайнера экрана. Перейдите на вкладку Properties. Нажмите на кнопку рядом с полем Caption и задайте локализованные заголовки экрана. Повторите те же действия для другого экрана. Для редактирования всех локализованных сообщений экранов сразу можно воспользоваться элементом messages.properties, расположенным в том же пакете, что и экраны. Выделите его и нажмите Edit, в появившемся редакторе задайте сообщения browseCaption и editCaption на доступных языках.

3.5.2. Экраны управления Заказами

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

Для этого перейдите на вкладку Entities на панели навигатора, выделите сущность Order и нажмите на кнопку New view. Отобразится страница дизайнера представлений. В качестве имени введите orderWithCustomer, в списке атрибутов нажмите на атрибут customer и на отобразившейся справа панели выберите представление _minimal для сущности Customer.

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

Далее выделите сущность Order и нажмите на кнопку Create standard screens. В отобразившемся окне Create standard screens в качестве Browse view и Edit view выберите значение orderWithCustomer и нажмите на кнопку Create.

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

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

3.5.3. Меню приложения

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

В поле Id введите новое значение идентификатора меню − shop, нажмите на кнопку Caption edit и задайте локализованное название пункта меню.

После редактирования меню нажмите на кнопку OK в верхнем левом углу рабочей панели.

3.5.4. Экран редактирования Покупателя со списком Заказов

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

  • Перейдите на вкладку Screens на панели навигатора. Выделите экран customer-edit.xml и нажмите на кнопку Edit.

  • На странице дизайнера экрана перейдите на вкладку Datasources и нажмите на кнопку New.

  • Выделите только что созданный источник данных в списке. В правой части страницы отобразятся его характеристики.

  • В поле Type укажите collectionDatasource.

  • В поле Id введите значение идентификатора источника данных − ordersDs.

  • В списке Entity выберите сущность com.sample.sales.entity.Order.

  • В списке View выберите представление _local.

  • В поле Query введите следующий запрос:

    select o from sales$Order o where o.customer.id = :ds$customerDs order by o.date

    Здесь запрос содержит условие отбора Заказов с параметром ds$customerDs. Значением параметра с именем вида ds${datasource_name} будет идентификатор сущности, установленной в данный момент в источнике данных datasource_name, в данном случае − идентификатор редактируемого Покупателя.

  • Нажмите на кнопку Apply для сохранения изменений.

  • Далее перейдите на вкладку Layout в дизайнере экрана и в палитре компонентов найдите компонент Label. Перетащите этот компонент на панель иерархии компонентов экрана, между fieldGroup и windowActions. Перейдите на вкладку Properties на панели свойств. В качестве значения поля value введите msg://orders. Нажмите на кнопку рядом с полем value и задайте локализованное значение надписи.

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

  • Перетащите компонент Table из палитры компонентов на панель иерархии компонентов между label и windowActions. Выделите компонент в иерархии и на панели свойств на вкладке Layout задайте размеры таблицы: в поле width укажите 100%, в поле height установите значение 200px. Перейдите на вкладку Properties. В качестве идентификатора укажите значение ordersTable, из списка доступных источников данных выберите orderDs.

    Далее нажмите на кнопку edit, относящуюся к columns. На экране отобразится диалоговое окно управления колонками таблицы. В первой строке в колонке id из выпадающего списка выберите значение date, во второй строке − amount.

  • Для сохранения изменений в экране редактирования Покупателя нажмите на кнопку OK в верхнем левом углу рабочей панели.

3.6. Запуск приложения

Посмотрим, как созданные нами экраны выглядят в работающем приложении. Для этого выполните Run > Restart application.

Зайдите в систему, выбрав русский язык в окне логина. Откройте пункт меню Продажи > Покупатели:

Рисунок 1. Экран списка Покупателей

Экран списка Покупателей


Нажмите на кнопку Создать:

Рисунок 2. Экран редактирования Покупателя

Экран редактирования Покупателя


Откройте пункт меню Продажи > Заказы:

Рисунок 3. Экран списка Заказов

Экран списка Заказов


Нажмите на кнопку Создать:

Рисунок 4. Экран редактирования Заказа

Экран редактирования Заказа


Глава 4. Устройство платформы

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

4.1. Архитектура

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

4.1.1. Уровни и блоки приложения

Платформа позволяет строить приложения по классической трехуровневой схеме: клиентский уровень, средний слой, база данных. Уровень отражает степень "удаленности" от хранимых данных.

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

На каждом уровне возможно создание одного или нескольких блоков (units) приложения. Блок представляет собой обособленную исполняемую программу, взаимодействующую с другими блоками приложения. Средства платформы CUBA позволяют создавать блоки в виде веб-приложений и десктопных приложений. Разработка блоков для мобильных платформ на данный момент остается за рамками CUBA, однако такие блоки, созданные другими средствами, могут быть интегрированы со стандартными блоками приложения.

Рисунок 5. Уровни и блоки приложения

Уровни и блоки приложения

Middleware

Средний слой, содержащий основную бизнес-логику приложения и выполняющий обращения к базе данных. Представляет собой отдельное веб-приложение под управлением стандартного контейнера Java EE Web Profile. См. Раздел 4.4, «Компоненты среднего слоя»

Web Client

Основной блок клиентского уровня. Содержит интерфейс, предназначенный, как правило, для внутренних пользователей организации. Представляет собой отдельное веб-приложение под управлением стандартного контейнера Java EE Web Profile. Реализация пользовательского интерфейса основана на фреймворке Vaadin. См. Раздел 4.5, «Универсальный пользовательский интерфейс»

Desktop Client

Дополнительный блок клиентского уровня. Содержит интерфейс, предназначенный, как правило, для внутренних пользователей организации. Представляет собой десктопное Java-приложение, реализация пользовательского интерфейса основана на фреймворке Java Swing. См. Раздел 4.5, «Универсальный пользовательский интерфейс»

Web Portal

Дополнительный блок клиентского уровня. Содержит интерфейс для внешних пользователей и средства интеграции с мобильными устройствами и сторонними приложениями. Представляет собой отдельное веб-приложение под управлением стандартного контейнера Java EE Web Profile. Реализация пользовательского интерфейса основана на фреймворке Spring MVC. См. Раздел 4.6, «Компоненты портала»

Обязательным блоком любого приложения является средний слой - Middleware. Для реализации пользовательского интерфейса, как правило, используется один или несколько клиентских блоков, например, Web Client и Web Portal.

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

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

4.1.2. Модули приложения

Модуль – наименьшая структурная единица CUBA-приложения. Представляет собой один модуль проекта приложения и соответствующий ему JAR файл с исполняемым кодом.

Стандартные модули:

  • global – включает в себя классы сущностей, интерфейсы сервисов и другие общие для всех уровней классы. Используется во всех блоках приложения.

  • core – реализация сервисов и всех остальных компонентов среднего слоя. Используется только на Middleware.

  • gui – общие компоненты универсального пользовательского интерфейса. Используется в Web Client и Desktop Client.

  • web – реализация универсального пользовательского интерфейса на Vaadin, а также другие специфичные для веб-клиента классы. Используется в блоке Web Client.

  • desktop – опциональный модуль – реализация универсального пользовательского интерфейса на Java Swing, а также другие специфичные для десктоп-клиента классы. Используется в блоке Desktop Client.

  • portal – опциональный модуль – реализация веб-портала на Spring MVC.

Рисунок 6. Модули приложения

Модули приложения

4.1.3. Базовые проекты

Функциональность платформы разделена на несколько так называемых базовых проектов:

  • cuba – основной базовый проект, содержит всю функциональность, описанную в данном руководстве, плюс подсистему безопасности (управление пользователями и их доступом к данным)

  • reports – подсистема генерации отчетов

  • workflow – подсистема управления потоками работ со встроенным визуальным редактором бизнес-процессов

  • fts – подсистема полнотекстового поиска

  • charts – подсистема вывода диаграмм

  • ccpayments – подсистема работы с кредитными картами

  • bpmn – механизм исполнения бизнес-процессов по стандарту BPMN 2.0

Создаваемое на основе платформы приложение может включать в себя функциональность базовых проектов путем объявления зависимостей от их артефактов. Зависимость от артефактов cuba является обязательной. Опциональные базовые проекты в свою очередь также зависят от cuba, и в принципе могут содержать зависимости между собой.

Рисунок 7. Зависимости между проектами

Зависимости между проектами

Сплошными линиями изображены обязательные зависимости, пунктирными − опциональные.

4.1.4. Состав приложения

Вышеописанные архитектурные принципы напрямую отражаются на составе собранного приложения. Рассмотрим его на примере простого приложения sales, которое имеет 2 блока – Middleware и Web Client; и включает в себя функциональность базовых проектов cuba и reports.

Рисунок 8. Состав простого приложения

Состав простого приложения

На рисунке изображено содержимое некоторых каталогов сервера Tomcat с развернутым в нем приложением sales.

Блок Middleware реализован веб-приложением app-core, блок Web Client – веб-приложением app. Исполняемый код веб-приложений содержится в каталогах WEB-INF/lib в наборе JAR-файлов. Каждый JAR представляет собой результат сборки (артефакт) одного из модулей приложения или базового проекта.

Например, состав JAR-файлов веб-приложения среднего слоя app-core определяется тем, что блок Middleware состоит из модулей global и core, и приложение использует базовые проекты cuba и reports (в данном случае версии 4.0.0).

4.2. Общие компоненты

В данной главе рассмотрены компоненты платформы, общие для всех уровней приложения.

4.2.1. Модель данных

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

Сущности подразделяются на две категории:

  • персистентные – экземпляры таких сущностей хранятся в таблицах базы данных

  • неперсистентные – экземпляры существуют только в оперативной памяти

Сущности характеризуются своими атрибутами. Атрибут соответствует полю класса и паре методов доступа (get / set) к полю. Чтобы атрибут был неизменяемым (read only), достаточно не создавать метод set.

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

Класс сущности должен удовлетворять следующим требованиям:

  • наследоваться от одного из базовых классов, предоставляемых платформой (см. ниже)

  • иметь набор полей и методов доступа, соответствующих атрибутам сущностей

  • класс и его поля (или методы доступа при отсутствии для атрибута соответствующего поля) должны быть определенным образом аннотированы для работы JPA (в случае персистентной сущности) и фреймворка метаданных

  • для поддержки возможного расширения сущностей поля класса необходимо объявлять с модификатором protected, а не private

Поддерживаются следующие типы атрибутов сущностей:

  • java.lang.String

  • java.lang.Boolean

  • java.lang.Integer

  • java.lang.Long

  • java.lang.Double

  • java.math.BigDecimal

  • java.util.Date

  • java.sql.Date

  • java.sql.Time

  • java.util.UUID

  • byte[]

  • enum

  • сущность

Базовые классы сущностей (см. ниже) переопределяют equals() и hashCode() таким образом, что экземпляры сущностей сравниваются по их глобальным уникальным идентификаторам (UUID). То есть экземпляры считаются равными, если равны их идентификаторы. Глобальный уникальный идентификатор присваивается сразу после создания экземпляра в памяти, поэтому новые экземпляры также можно сравнивать и помещать в коллекции.

4.2.1.1. Базовые классы сущностей

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

Рисунок 9. Базовые классы сущностей

Базовые классы сущностей

  • Instance – декларирует базовые методы работы с объектами предметной области:

    • Получение глобального уникального идентификатора (UUID) сущности.

    • Получение ссылки на мета-класс объекта.

    • Генерация имени экземпляра.

    • Чтение/установка значений атрибутов по имени.

    • Добавление слушателей, получающих уведомления об изменениях атрибутов.

  • Entity – дополняет Instance понятием идентификатора сущности (который не обязательно равен UUID), причем Entity не определяет тип идентификатора, оставляя эту возможность наследникам.

  • AbstractInstance – реализует логику работы со слушателями изменения атрибутов.

    AbstractInstance хранит слушателей в коллекции WeakReference, т.е. при отсутствии внешних ссылок на добавленного слушателя, он будет немедленно уничтожен сборщиком мусора. Как правило, слушателями изменения атрибутов являются визуальные компоненты и источники данных UI, на которые всегда имеются ссылки из других объектов, поэтому проблема исчезновения слушателей не возникает. Однако если слушатель создается прикладным кодом и на него никто не ссылается естественным образом, необходимо кроме добавления в Instance сохранить его в некотором поле объекта.

  • AbstractNotPersistentEntity – базовый класс неперсистентных сущностей с идентификаторами типа UUID.

  • BaseEntity – базовый интерфейс всех персистентных сущностей, декларирует методы получения информации о том, кто и когда создал экземпляр сущности в базе данных.

  • BaseGenericIdEntity - реализует BaseEntity и добавляет аннотации для поддержки JPA, не специфицируя при этом тип идентификатора (то есть первичного ключа) сущности.

  • BaseUuidEntity - расширяет BaseGenericIdEntity, задавая атрибут-идентификатор с именем id типа UUID.

  • BaseLongIdEntity - расширяет BaseGenericIdEntity, задавая атрибут-идентификатор с именем id типа Long.

  • BaseIntegerIdEntity - расширяет BaseGenericIdEntity, задавая атрибут-идентификатор с именем id типа Integer.

  • BaseStringIdEntity - расширяет BaseGenericIdEntity, задавая только тип идентификатора - String. В конкретном классе сущности, унаследованной от BaseStringIdEntity, необходимо задать атрибут-идентификатор типа String и добавить ему JPA-аннотацию @Id.

  • Versioned – интерфейс сущностей, поддерживающих оптимистичную блокировку

  • Updatable – интерфейс сущностей, для которых требуется сохранять информацию о том, кто и когда изменял экземпляр в последний раз

  • SoftDelete – интерфейс сущностей, поддерживающих мягкое удаление

  • StandardEntity – наиболее часто используемый базовый класс персистентных сущностей, имеющий идентификатор типа UUID и реализующий интерфейсы Versioned, Updatable, SoftDelete.

При создании классов сущностей рекомендуется выбирать базовый класс по следующим правилам:

  • Если сущность не хранится в БД, наследуйте ее от AbstractNotPersistentEntity.

  • Если сущность встраиваемая - наследуйте ее от EmbeddableEntity.

  • Если сущность только создается в БД, никогда не изменяется, и мягкое удаление не требуется - наследуйте ее от BaseUuidEntity.

  • Если сущность ведет себя стандартным образом: изменяется в БД, требует оптимистичной блокировки и мягкого удаления − наследуйте ее от StandardEntity.

  • В противном случае наследуйте сущность от BaseUuidEntity и реализуйте в классе тот набор интерфейсов Versioned, Updatable, SoftDelete, который требуется.

  • Иногда для некоторых сущностей желательно использовать целочисленные или строковые первичные ключи. В этом случае вместо BaseUuidEntity унаследуйте класс сущности от BaseLongIdEntity, BaseIntegerIdEntity, или BaseStringIdEntity.

4.2.1.2. Аннотации сущностей

В данном разделе описаны все поддерживаемые платформой аннотации классов и атрибутов сущностей.

Аннотации пакета javax.persistence обеспечивают работу JPA, аннотации пакетов com.haulmont.* предназначены для управления метаданными и другими механизмами платформы.

Если для аннотации указано только простое имя класса, подразумевается что это класс платформы, расположенный в одном из пакетов com.haulmont.*

4.2.1.2.1. Аннотации класса
@javax.persistence.Entity

Объявляет класс сущностью модели данных.

Параметры:

  • name - имя сущности, обязательно должно начинаться с префикса, отделенного знаком $. Желательно использовать в качестве префикса короткое имя проекта для формирования отдельного пространства имен.

Пример:

@Entity(name = "sales$Customer")
@javax.persistence.MappedSuperclass

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

@javax.persistence.Table

Определяет таблицу базы данных для данной сущности.

Параметры:

  • name - имя таблицы

Пример:

@Table(name = "SALES_CUSTOMER")
@javax.persistence.Embeddable

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

Для задания имени сущности требуется применение аннотации @MetaClass .

@javax.persistence.Inheritance

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

Параметры:

  • strategy - стратегия, по умолчанию SINGLE_TABLE

@javax.persistence.DiscriminatorColumn

Используется для определения колонки БД, отвечающей за различение типов сущностей в случае стратегий наследования SINGLE_TABLE и JOINED.

Параметры:

  • name - имя колонки-дискриминатора

  • discriminatorType - тип данных колонки-дискриминатора

Пример:

@DiscriminatorColumn(name = "TYPE", discriminatorType = DiscriminatorType.INTEGER)
@javax.persistence.DiscriminatorValue

Определяет значение колонки-дискриминатора для данной сущности. Эта аннотация должна быть помещена на конкретном классе сущности.

Пример:

@DiscriminatorValue("0")
@javax.persistence.PrimaryKeyJoinColumn

Используется в случае стратегии наследования JOINED для указания колонки внешнего ключа данной сущности, ссылающегося на первичный ключ сущности-предка.

Параметры:

  • name - имя колонки внешнего ключа данной сущности

  • referencedColumnName - имя колонки первичного ключа сущности предка

Пример:

@PrimaryKeyJoinColumn(name = "CARD_ID", referencedColumnName = "ID")
@NamePattern

Определяет способ получения имени экземпляра, возвращаемого методом Instance.getInstanceName().

Значением аннотации должна быть строка вида {0}|{1}, где

  • {0} - строка форматирования по правилам String.format(), или имя метода данного объекта с префиксом #. Метод должен возвращать String и не иметь параметров.

  • {1} - разделенный запятыми список имен полей класса, соответствующий формату {0}. В случае использования в {0} метода список полей все равно необходим, так как по нему формируется представление _minimal.

Примеры:

@NamePattern("%s|name")
@NamePattern("#getCaption|login,name")
@Listeners

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

Значением аннотации должна быть строка или массив строк с именами классов слушателей - см. Раздел 4.4.4.6, «Entity Listeners»

Строки используются здесь вместо ссылок на классы потому, что классы слушателей находятся только на уровне Middleware и не доступны клиентскому коду, в то время как классы самих сущностей используются на всех уровнях.

Примеры:

@Listeners("com.haulmont.cuba.security.listener.UserEntityListener")
@Listeners({"com.abc.sales.entity.FooListener","com.abc.sales.entity.BarListener"})
@MetaClass

Используется для объявления неперсистентной или встраиваемой сущности (т.е. когда аннотация @javax.persistence.Entity не применима)

Параметры:

  • name - имя сущности, обязательно должно начинаться с префикса, отделенного знаком $. Желательно использовать в качестве префикса короткое имя проекта для формирования отдельного пространства имен.

Пример:

@MetaClass(name = "sys$LockInfo")
@SystemLevel

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

@EnableRestore

Указывает, что экземпляры данной сущности доступны для восстановления после мягкого удаления в специальном экране core$Entity.restore.

@TrackEditScreenHistory

Указывает, что для данной сущности будет запоминаться история открытия экранов редактирования ({имя_сущности}.edit) с возможностью отображения в специальном экране sec$ScreenHistory.browse.

@Extends

Указывает, что данная сущность является расширением и должна повсеместно использоваться вместо базовой. См. Раздел 4.8, «Расширение функциональности»

@PostConstruct

Данная аннотация может быть указана для метода класса. Такой метод будет вызван сразу после создания экземпляра сущности через Metadata.create(). Это удобно, если для инициализации экземпляра сущности требуется вызов каких-либо бинов. Пример см. в Раздел 5.8.2.1, «Инициализация полей сущности».

4.2.1.2.2. Аннотации атрибутов

Аннотации атрибутов устанавливаются на соответствующие поля класса, за одним исключением: если требуется объявить неизменяемый (read only) неперсистентный атрибут foo, то достаточно создать метод доступа getFoo() и поместить на этот метод аннотацию @MetaProperty.

@javax.persistence.Transient

Указывает, что данное поле не хранится в БД, т.е. является неперсистентным.

Поля поддерживаемых JPA типов (см. http://docs.oracle.com/javaee/5/api/javax/persistence/Basic.html) по умолчанию являются персистентными, поэтому аннотация @Transient обязательна для объявления неперсистентного атрибута такого типа.

Для включения @Transient атрибута в метаданные, необходимо также указать аннотацию @MetaProperty .

@org.apache.openjpa.persistence.Persistent

Указывает, что данное поле хранится в БД, т.е. является персистентным.

Данная аннотация требуется только для нестандартного для JPA типа поля, платформа на данный момент поддерживает один такой тип - java.util.UUID. Таким образом, @Persistent требуется только в одном случае - при объявлении персистентного поля типа UUID.

@javax.persistence.Column

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

Параметры:

  • name - имя колонки

  • length - (необязательный параметр, по умолчанию 255) - длина колонки. Используется также при формировании метаданных и, в конечном счете, может ограничивать максимальную длину вводимого текста в визуальных компонентах, работающих с данным атрибутом. Для отмены ограничения по длине атрибуту необходимо добавить аннотацию @Lob.

  • nullable - (необязательный параметр, по умолчанию true) - может ли атрибут содержать null. При указании nullable = false JPA контролирует наличие значения поля при сохранении, кроме того, визуальные компоненты, работающие с данным атрибутом, могут сигнализировать пользователю о необходимости ввода значения.

@javax.persistence.Id

Указывает, что данный атрибут является первичным ключом сущности. Обычно эта аннотация присутствует на поле базового класса, такого как BaseUuidEntity. Использовать эту аннотацию в конкретном классе сущности необходимо только при наследовании от базового класса BaseStringIdEntity (то есть при создании сущности со строковым первичным ключом).

@javax.persistence.ManyToOne

Определяет атрибут-ссылку на сущность с типом ассоциации много-к-одному.

Параметры:

  • fetch - (по умолчанию EAGER) параметр, определяющий, будет ли JPA жадно загружать ассоциированную сущность. Данный параметр всегда должен быть установлен в значение LAZY, так как в CUBA-приложении политика загрузки связей определяется динамически на основе механизма представлений.

  • optional - (необязательный параметр, по умолчанию true) - может ли атрибут содержать null. При указании optional = false JPA контролирует наличие ссылки при сохранении, кроме того, визуальные компоненты, работающие с данным атрибутом, могут сигнализировать пользователю о необходимости ввода значения.

Например, несколько экземпляров Order (заказов) ссылаются на один экземпляр Customer (покупателя), в этом случае класс Order должен содержать следующее объявление:

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "CUSTOMER_ID")
protected Customer customer;
@javax.persistence.OneToMany

Определяет атрибут-коллекцию ссылок на сущность с типом ассоциации один-ко-многим.

Параметры:

  • mappedBy - поле связанной сущности, определяющее ассоциацию

  • targetEntity - тип связанной сущности. Необязательный параметр, если коллекция объявлена с использованием Java generics.

  • fetch - (необязательный параметр, по умолчанию LAZY) - определяет, будет ли JPA жадно загружать коллекцию связанных сущностей. Необходимо всегда оставлять значение по умолчанию LAZY, так как в CUBA-приложении политика загрузки связей определяется динамически на основе механизма представлений.

  • cascade - (необязательный параметр, по умолчанию {}) - каскадирование операций определяет, какие операции над сущностью должны быть применены к ассоциированным сущностям. Каскадирование на данном уровне не рекомендуется использовать.

Например, несколько экземпляров Item (пунктов заказа) ссылаются на один экземпляр Order (заказ) с помощью @ManyToOne поля Item.order, в этом случае класс Order может содержать коллекцию экземпляров Item:

@OneToMany(mappedBy = "order")
protected Set<Item> items;
@javax.persistence.OneToOne

Определяет атрибут-ссылку на сущность с типом ассоциации один-к-одному.

Параметры:

  • fetch - (по умолчанию EAGER) параметр, определяющий, будет ли JPA жадно загружать ассоциированную сущность. Данный параметр всегда должен быть установлен в значение LAZY, так как в CUBA-приложении политика загрузки связей определяется динамически на основе механизма представлений.

  • mappedBy - поле связанной сущности, определяющее ассоциацию. Требуется устанавливать только на ведомой стороне ассоциации.

  • optional - (необязательный параметр, по умолчанию true) - может ли атрибут содержать null. При указании optional = false JPA контролирует наличие ссылки при сохранении, кроме того, визуальные компоненты, работающих с данным атрибутом, могут сигнализировать пользователю о необходимости ввода значения.

Пример ведущей стороны ассоциации, класс Driver:

@OneToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "CALLSIGN_ID")
protected DriverCallsign callsign;

Пример ведомой стороны ассоциации, класс DriverCallsign:

@OneToOne(fetch = FetchType.LAZY, mappedBy = "callsign")
protected Driver driver;
@javax.persistence.ManyToMany

Определяет атрибут-коллекцию ссылок на сущность с типом ассоциации много-ко-многим.

Ассоциация много-ко-многим всегда имеет ведущую сторону и может иметь обратную сторону - ведомую. На ведущей стороне указывается дополнительная аннотация @JoinTable, на ведомой стороне - параметр mappedBy.

Параметры:

  • mappedBy - поле связанной сущности, определяющее ассоциацию с ведущей стороны. Необходимо указывать только на ведомой стороне.

  • targetEntity - тип связанной сущности. Необязательный параметр, если коллекция объявлена с использованием Java generics.

  • fetch - (необязательный параметр, по умолчанию LAZY) - определяет, будет ли JPA жадно загружать коллекцию связанных сущностей. Необходимо всегда оставлять значение по умолчанию LAZY, так как в CUBA-приложении политика загрузки связей определяется динамически на основе механизма представлений.

@javax.persistence.JoinColumn

Используется для указания колонки БД, определяющей ассоциацию между сущностями.

Параметры:

  • name - имя колонки

Пример:

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "CUSTOMER_ID")
protected Customer customer;
@javax.persistence.JoinTable

Используется для указания таблицы связи на ведущей стороне @ManyToMany ассоциации.

Параметры:

  • name - имя таблицы связи

  • joinColumns - элемент @JoinColumn, определяющий колонку таблицы связей, соответствующую первичному ключу ведущей стороны ассоциации (т.е. содержащей аннотацию @JoinTable)

  • inverseJoinColumns - элемент @JoinColumn, определяющий колонку таблицы связей, соответствующую первичному ключу ведомой стороны ассоциации

Пример атрибута customers класса Group, являющегося ведущей стороной ассоциации:

@ManyToMany
@JoinTable(name = "SALES_CUSTOMER_GROUP_LINK",
  joinColumns = @JoinColumn(name = "GROUP_ID"),
  inverseJoinColumns = @JoinColumn(name = "CUSTOMER_ID"))
protected Set<Customer> customers;

Пример атрибута groups класса Customer, являющегося ведомой стороной этой же ассоциации:

@ManyToMany(mappedBy = "customers")
protected Set<Group> groups;
@javax.persistence.OrderBy

Определяет порядок элементов в атрибуте-коллекции на момент извлечения из базы данных. Данную аннотацию необходимо задавать для упорядоченных коллекций, таких как List или LinkedHashSet для получения предсказуемого порядка следования элементов.

Параметры:

  • value - строка, определяющая порядок, в формате:

    orderby_list::= orderby_item [,orderby_item]*
    orderby_item::= property_or_field_name [ASC | DESC]

Пример:

@OneToMany(mappedBy = "user")
@OrderBy("createTs")
protected List<UserRole> userRoles;
@javax.persistence.Embedded

Определяет атрибут типа встраиваемой сущности, в свою очередь аннотированной @Embeddable.

Пример:

@Embedded
protected Address address;
@javax.persistence.Temporal

Для атрибута типа java.util.Date уточняет тип хранимого значения: дата, время или дата+время.

Параметры:

  • value - тип хранимого значения: DATE, TIME, TIMESTAMP

Пример:

@Column(name = "START_DATE")
@Temporal(TemporalType.DATE)
protected Date startDate;
@javax.persistence.Version

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

Применение такого поля необходимо при реализации классом сущности интерфейса Versioned (базовый класс StandardEntity уже содержит такое поле).

Пример:

@Version
@Column(name = "VERSION")
private Integer version;
@javax.persistence.Lob

Указывает, что данный атрибут не имеет ограничений длины. Применяется совместно с аннотацией @Column. Если @Lob указан, то длина, заданная в @Column явно или по умолчанию, игнорируется.

Пример:

@Column(name = "DESCRIPTION")
@Lob
private String description;
@MetaProperty

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

Данная аннотация не обязательна для полей, снабженных следующими аннотациями пакета javax.persistence: @Column, @OneToOne, @OneToMany, @ManyToOne, @ManyToMany, @Embedded. Такие поля отражаются в метаданных автоматически. Поэтому @MetaProperty в основном применяется для определения неперсистентных атрибутов сущностей.

Параметры:

  • mandatory - (необязательный параметр, по умолчанию false) - может ли атрибут содержать null. При указании mandatory = true визуальные компоненты, работающие с данным атрибутом, могут сигнализировать пользователю о необходимости ввода значения.

Пример использования для поля:

@Transient
@MetaProperty
protected String token;

Пример использования для метода:

@MetaProperty
public String getLocValue() {
  if (!StringUtils.isBlank(messagesPack)) {
      return AppBeans.get(Messsages.class).getMessage(messagesPack, value);
  } else {
      return value;
  }
}
@OnDelete

Определяет политику обработки связи в случае мягкого удаления сущности, содержащей данный атрибут. См. Раздел 4.2.1.4, «Мягкое удаление»

Пример:

@OneToMany(mappedBy = "group")
@OnDelete(DeletePolicy.CASCADE)
private Set<Constraint> constraints;
@OnDeleteInverse

Определяет политику обработки связи в случае мягкого удаления сущности с обратной стороны ассоциации. См. Раздел 4.2.1.4, «Мягкое удаление»

Пример:

@ManyToOne
@JoinColumn(name = "DRIVER_ID")
@OnDeleteInverse(DeletePolicy.DENY)
private Driver driver;
@Composition

Указывает на то, что связь является композицией - более тесным вариантом ассоциации. Это означает, что связанная сущность имеет смысл только как часть владеющей сущности, т.е. создается и удаляется вместе с ней.

Например, список пунктов в заказе (класс Order содержит коллекцию экземпляров Item):

@OneToMany(mappedBy = "order")
@Composition
protected List<Item> items;

Указание для связи аннотации @Composition позволяет организовать в экранах редактирования специальный режим коммита источников данных, при котором изменения экземпляров детализирующей сущности сохраняются в базе данных только при коммите основной сущности. Подробнее см. Раздел 5.8.3, «Редактирование композитных сущностей».

@LocalizedValue

Служит для описания способа получения локализованного значения некоторого изменяющегося атрибута, которое возвращает метод MessageTools.getLocValue().

Параметры:

  • messagePack - явное указание пакета, из которого будет взято локализованное сообщение, например, com.haulmont.cuba.core.entity

  • messagePackExpr - выражение в терминах пути к атрибуту, хранящему имя пакета, из которого будет взято локализованное сообщение, например proc.messagesPack. Путь начинается с атрибута текущей сущности.

Пример аннотации, означающей, что локализованное значение атрибута state будет взято из пакета, имя которого хранится в атрибуте messagesPack связанной сущности proc:

@Column(name = "STATE")
@LocalizedValue(messagePackExpr = "proc.messagesPack")
protected String state;

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "PROC_ID")
protected Proc proc;
@IgnoreUserTimeZone

Для атрибутов типа timestamp с аннотацией @javax.persistence.Temporal.TIMESTAMP заставляет платформу игнорировать часовой пояс пользователя, если он задан для текущей сессии.

4.2.1.3. Атрибуты типа enum

В стандартном варианте использования JPA для атрибутов типа enum в базе данных хранится целое число, получаемое методом ordinal() этого перечисления. Такой подход может привести к следующим проблемам при эксплуатации и развитии системы:

  • при появлении в БД значения, не равного ни одному ordinal значению перечисления, экземпляр сущности нельзя загрузить вообще;

  • невозможно ввести новое значение между имеющимися, что актуально при использовании сортировки по значению перечисления (order by).

Чтобы решить эти проблемы, в подходе CUBA предлагается отвязать значение, хранимое в БД, от ordinal перечисления. Для этого необходимо поле класса сущности объявлять с типом, хранимым в БД (Integer или String), а методы доступа (getter / setter) создавать для типа самого перечисления.

Например:

@Entity(name = "sales$Customer")
@Table(name = "SALES_CUSTOMER")
public class Customer extends StandardEntity {

  @Column(name = "GRADE")
  protected Integer grade;

  public CustomerGrade getGrade() {
      return grade == null ? null : CustomerGrade.fromId(grade);
  }

  public void setGrade(CustomerGrade grade) {
      this.grade = grade == null ? null : grade.getId();
  }
...
}  

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

public enum CustomerGrade implements EnumClass<Integer> {

  PREMIUM(10),
  HIGH(20),
  MEDIUM(30);

  private Integer id;

  CustomerGrade(Integer id) {
      this.id = id;
  }

  @Override
  public Integer getId() {
      return id;
  }

  public static CustomerGrade fromId(Integer id) {
      for (CustomerGrade grade : CustomerGrade.values()) {
          if (grade.getId().equals(id))
              return grade;
      }
      return null;
  }
}

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

Как видно из примеров, для атрибута grade в БД хранится значение типа Integer, задаваемое полем id перечисления CustomerGrade, а конкретно 10, 20 или 30. В то же время прикладной код и метаданные работают с самим типом CustomerGrade через методы доступа, которые и осуществляют конвертацию.

При наличии в поле БД значения, не соответствующего ни одному значению перечисления, метод getGrade() просто вернет null. Для ввода нового значения, например, HIGHER, между HIGH и PREMIUM, достаточно добавить это значение в перечисление с идентификатором 15, при этом сортировка по полю Customer.grade останется верной.

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

4.2.1.4. Мягкое удаление

Платформа CUBA поддерживает режим "мягкого удаления" данных - когда вместо удаления записей из базы данных они только помечаются определенным образом и становятся недоступными для обычного использования. В дальнейшем такие записи можно либо совсем удалить из БД с помощью отдельной регламентной процедуры, либо восстановить.

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

Режим мягкого удаления имеет следующие преимущества:

  • значительно снижается риск потери данных вследствие неверных действий пользователей

  • позволяет быстро сделать некоторые записи недоступными, даже если на них имеются ссылки.

    Возьмем для примера модель данных Заказы - Покупатели. Допустим, на некоторого покупателя оформлено несколько заказов, однако нам нужно сделать его недоступным для дальнейшей работы. Традиционным "жестким" удалением сделать это невозможно, так как для удаления покупателя нам нужно либо удалить все его заказы, либо обнулить в этих заказах ссылки на него (т.е. потерять информацию). При мягком удалении покупателя он становится недоступным для поиска и изменения, однако при просмотре заказов пользователь видит на экране название покупателя, так как при загрузке связей признак удаления намеренно игнорируется.

    Описанное поведение является стандартным, но может быть модифицировано с помощью политики обработки связей при удалении.

Отрицательной стороной мягкого удаления является увеличение объема базы данных и потенциальная необходимость дополнительных процедур ее очистки.

4.2.1.4.1. Использование

Для того чтобы экземпляры сущности удалялись мягко, класс сущности должен реализовывать интерфейс SoftDelete, а соответствующая таблица БД должна содержать колонки:

  • DELETE_TS - когда удалена запись

  • DELETED_BY - логин пользователя, который удалил запись

Поведение системы по умолчанию - сущности, реализующие SoftDelete, удаляются мягко, удаленные сущности не возвращаются запросами и поиском по идентификатору. При необходимости такое поведение можно динамически отключить следующими способами:

  • для текущего экземпляра EntityManager - вызовом setSoftDeletion(false)

  • при запросе данных через DataManager - вызовом у передаваемого объекта LoadContext метода setSoftDeletion(false)

  • на уровне источников данных - используя метод CollectionDatasource.setSoftDeletion(false) или атрибут softDeletion="false" элемента collectionDatasource в XML-дескрипторе экрана.

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

4.2.1.4.2. Политика обработки связей

Платформа предоставляет средство обработки связей при удалении сущностей, во многом аналогичное правилам ON DELETE внешних ключей в базе данных. Это средство работает на уровне Middleware и использует аннотации @OnDelete, @OnDeleteInverse атрибутов сущности.

Аннотация @OnDelete обрабатывается при удалении той сущности, в которой она встретилась, а не той, на которую указывает аннотированный атрибут (в этом отличие от каскадных удалений на уровне БД).

Аннотация @OnDeleteInverse обрабатывается при удалении той сущности, на которую указывает аннотированный атрибут, (т.е. аналогично каскадному удалению на уровне внешних ключей в БД). Эта аннотация полезна при отсутствии в удаляемом объекте атрибута, который нужно проверять при удалении. При этом, как правило, в проверяемом объекте существует ссылка на удаляемый, на этот атрибут и устанавливается аннотация @OnDeleteInverse.

Значением аннотации может быть:

  • DeletePolicy.DENY - запретить удаление сущности, если аннотированный атрибут не null или не пустая коллекция

  • DeletePolicy.CASCADE - каскадно удалить аннотированный атрибут

  • DeletePolicy.UNLINK - разорвать связь с аннотированным атрибутом. Разрыв связи имеет смысл указывать только на ведущей стороне ассоциации - той, которая в классе сущности аннотирована @JoinColumn.

Примеры:

  1. Запрет удаления при наличии ссылки: при попытке удаления экземпляра Customer, на который ссылается хотя бы один Order, будет выброшено исключение DeletePolicyException.

    Order.java

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "CUSTOMER_ID")
    @OnDeleteInverse(DeletePolicy.DENY)
    protected Customer customer;

    Customer.java

    @OneToMany(mappedBy = "customer")
    protected List<Order> orders;
  2. Каскадное удаление элементов коллекции: при удалении экземпляра Role все экземпляры Permission также будут удалены.

    Role.java

    @OneToMany(mappedBy = "role")
    @OnDelete(DeletePolicy.CASCADE)
    protected Set<Permission> permissions;

    Permission.java

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "ROLE_ID")
    protected Role role;
  3. Разрыв связи с элементами коллекции: удаление экземпляра Role приведет к установке в null ссылок со стороны всех входивших в коллекцию экземпляров Permission.

    Role.java

    @OneToMany(mappedBy = "role")
    protected Set<Permission> permissions;

    Permission.java

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "ROLE_ID")
    @OnDeleteInverse(DeletePolicy.UNLINK)
    protected Role role;

Особенности реализации:

  1. Нужно быть осторожным при использовании @OnDeleteInverse с политиками CASCADE и UNLINK, так как при этом происходит извлечение из БД на сервер приложения всех экземпляров ссылающихся объектов, изменение и затем сохранение.

    Например, в случае ассоциации Customer - Job и большого количества работ для одного заказчика, если поставить на атрибут Job.customer политику @OnDeleteInverse(CASCADE), то при удалении экземпляра заказчика будет предпринята попытка извлечь и изменить все его работы. Это может привести к перегрузке сервера приложения и БД.

    С другой стороны, использование @OnDeleteInverse(DENY) безопасно, так как при этом производится только подсчет количества ссылающихся объектов, и если оно больше 0, выбрасывается исключение. Поэтому @OnDeleteInverse(DENY) для атрибута Job.customer вполне допустимо.

  2. Политика обработки связей реализуется с помощью Entity Listeners, то есть при сохранении данных в БД на уровне Middleware.

4.2.1.4.3. Ограничение уникальности на уровне БД

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

Реализуется данная логика путем, специфичным для используемого сервера базы данных:

  • Если сервер БД поддерживает частичные (partial) индексы (например, PostgreSQL), то ограничение уникальности можно создать следующим образом:

    create unique index IDX_SEC_USER_UNIQ_LOGIN on SEC_USER (LOGIN_LC) where DELETE_TS is null
  • Если сервер БД не поддерживает частичные индексы (например, Microsoft SQL Server 2005), то в уникальный индекс можно включить поле DELETE_TS:

    create unique index IDX_SEC_USER_UNIQ_LOGIN on SEC_USER (LOGIN_LC, DELETE_TS)

4.2.2. Metadata Framework

Для эффективной работы с моделью данных в CUBA-приложениях используется фреймворк метаданных, который:

  • предоставляет удобный интерфейс для получения информации о сущностях, их атрибутах и отношениях между сущностями; а также для навигации по ссылкам

  • служит специализированной и более удобной в использовании альтернативой Java Reflection API

  • регламентирует допустимые типы данных и отношений между сущностями

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

4.2.2.1. Интерфейсы метаданных

Рассмотрим основные интерфейсы метаданных.

Рисунок 10. Интерфейсы фреймворка метаданных

Интерфейсы фреймворка метаданных

Session

Точка входа в фреймворк метаданных. Позволяет получать экземпляры MetaClass по имени и по соответствующему классу Java. Обратите внимание на различие методов getClass() и getClassNN() - первые могут возвращать null, вторые нет (NonNull).

Объект Session может быть получен через интерфейс инфраструктуры Metadata .

Пример:

@Inject
protected Metadata metadata;
...
Session session = metadata.getSession();
MetaClass metaClass1 = session.getClassNN("sec$User");
MetaClass metaClass2 = session.getClassNN(User.class);
assert metaClass1 == metaClass2;
MetaModel

Редко используемый интерфейс, служит для группировки мета-классов.

Группировка осуществляется по имени корневого Java пакета проекта, указываемого в файле metadata.xml .

MetaClass

Интерфейс метаданных класса сущности. MetaClass всегда ассоциирован с классом Java, которого он представляет.

Основные методы:

  • getName() – имя сущности, по соглашению первой частью имени до знака $ является код пространства имен, например, sales$Customer

  • getProperties() – список мета-свойств (MetaProperty)

  • getProperty(), getPropertyNN() - получение мета-свойства по имени. Первый метод в случае отсутствия атрибута с указанным именем возвращает null, второй выбрасывает исключение.

    Пример:

    MetaClass userClass = session.getClassNN(User.class);
    MetaProperty groupProperty = userClass.getPropertyNN("group");
  • getPropertyPath() - позволяет перемещаться по ссылкам. Данный метод принимает строковый параметр - путь из имен атрибутов, разделенных точкой. Возвращаемый объект MetaPropertyPath позволяет обратиться к искомому (последнему в пути) атрибуту вызовом getMetaProperty().

    Пример:

    MetaClass userClass = session.getClassNN(User.class);
    MetaProperty groupNameProp = userClass.getPropertyPath("group.name").getMetaProperty();
    assert groupNameProp.getDomain().getName().equals("sec$Group");
  • getJavaClass() – класс сущности, которому соответствует данный MetaClass

  • getAnnotations() – коллекция мета-аннотаций

MetaProperty

Интерфейс метаданных атрибута сущности.

Основные методы:

  • getName() – имя свойства, соответствует имени атрибута сущности

  • getDomain() – мета-класс, которому принадлежит данное свойство

  • getType() – тип свойства:

    • простой тип: DATATYPE

    • перечисление: ENUM

    • ссылочный тип двух видов:

      • ASSOCIATION − простая ссылка на другую сущность. Например, отношение заказа и покупателя − ассоциация.

      • COMPOSITION − ссылка на сущность, которая не имеет самостоятельного значения без владеющей сущности. COMPOSITION можно считать "более тесным" отношением, чем ASSOCIATION. Например, отношение заказа и пункта этого заказа − COMPOSITION, т.к. пункт не может существовать без заказа, которому он принадлежит.

      Вид ссылочного атрибута ASSOCIATION или COMPOSITION влияет на режим редактирования сущности: в первом случае сохранение связанной сущности в базу данных происходит независимо, а во втором − связанная сущность сохраняется в БД только вместе с владеющей сущностью.

  • getRange() – интерфейс Range, детально описывающий тип данного атрибута

  • isMandatory() – признак обязательности атрибута. Используется, например, визуальными компонентами для сигнализации пользователю о необходимости ввода значения.

  • isReadOnly() – признак неизменности атрибута

  • getInverse() – для ссылочного атрибута возвращает мета-свойство с обратной стороны ассоциации, если таковое имеется

  • getAnnotatedElement() – поле (java.lang.reflect.Field) или метод (java.lang.reflect.Method), соответствующие данному атрибуту сущности

  • getJavaType() – класс Java данного атрибута сущности. Это либо тип поля класса, либо тип возвращаемого значения метода.

  • getDeclaringClass() – класс Java, содержащий данный атрибут

Range

Интерфейс, детально описывающий тип атрибута сущности.

Основные методы:

  • isDatatype() – возвращает true для атрибута простого типа

  • asDatatype() - возвращает Datatype для атрибута простого типа

  • isEnum() – возвращает true для атрибута типа перечисления

  • asEnumeration() - возвращает Enumeration для атрибута типа перечисления

  • isClass() – возвращает true для ссылочного атрибута типа ASSOCIATION или COMPOSITION

  • asClass() - возвращает мета-класс ассоциированной сущности для ссылочного атрибута

  • isOrdered() – возвращает true если атрибут представляет собой упорядоченную коллекцию (например, List)

  • getCardinality() – вид отношения для ссылочного атрибута: ONE_TO_ONE, MANY_TO_ONE, ONE_TO_MANY, MANY_TO_MANY

4.2.2.2. Формирование метаданных

Основной источник формирования структуры метаданных - аннотированные классы сущностей.

Класс сущности отражается в метаданных в следующих случаях:

  • Класс персистентной сущности аннотирован @Entity, @Embeddable, @MappedSuperclass и расположен в пределах корневого пакета, указанного в metadata.xml .

  • Класс неперсистентной сущности аннотирован @MetaClass и расположен в пределах корневого пакета, указанного в metadata.xml.

Все сущности внутри одного корневого пакета помещаются в один экземпляр MetaModel, которому присваивается имя этого пакета. Между сущностями внутри одной MetaModel можно устанавливать произвольные связи, между разными - в порядке объявления файлов metadata.xml в свойстве cuba.metadataConfig .

Атрибут сущности отражается в метаданных, если:

  • поле класса аннотировано @Column, @OneToOne, @OneToMany, @ManyToOne, @ManyToMany, @Embedded

  • поле класса или метод доступа на чтение (getter) аннотирован @MetaProperty

Параметры мета-класса и мета-свойств формируются на основе параметров перечисленных аннотаций, а также типов полей и методов класса. Кроме того, если у атрибута отсутствует метод доступа на запись (setter), атрибут становится неизменяемым (read only).

4.2.2.3. Datatype

Интерфейс Datatype описывает тип данных, допустимый для атрибута сущности, не являющегося ассоциацией. Каждый экземпляр реализации Datatype соответствует одному классу Java, для работы с которым он предназначен.

Все экземпляры зарегистрированы в репозитории - классе Datatypes, который выполняет загрузку и инициализацию классов реализации Datatype следующим образом:

  • в корне CLASSPATH ищется файл datatypes.xml , и если он найден, репозиторий Datatypes инициализируется из него

  • в противном случае инициализация Datatypes производится из файла /com/haulmont/chile/core/datatypes/datatypes.xml

Экземпляр Datatype может быть получен двумя способами:

  • для атрибута сущности из соответствующего ему мета-свойства типа DATATYPE , вызовом getRange().asDatatype()

  • статическим методом Datatypes.get(), передавая в него имя реализации Datatype или класс Java, для которого он создан.

Datatype сопоставляется атрибуту сущности на старте системы по следующим правилам:

  • Если для поля или метода задана аннотация @MetaProperty с непустым значением datatype, то атрибуту сопоставляется экземпляр Datatype с данным именем.

    Например, при следующем объявлении атрибута сущности он получит нестандартный тип GeoCoordinateDatatype (см. пример ниже):

    @MetaProperty(datatype = GeoCoordinateDatatype.NAME)
    @Column(name = "LATITUDE")
    private Double latitude;
  • как правило, явное указание отсутствует, и атрибуту сопоставляется экземпляр Datatype, возвращаемый репозиторием Datatypes.get(Class), при передаче в него типа поля или метода.

    Например, в данном случае атрибут latitude получит стандартный тип DoubleDatatype, зарегистрированный в базовом /com/haulmont/chile/core/datatypes/datatypes.xml:

    @Column(name = "LATITUDE")
    private Double latitude;

Основные методы интерфейса Datatype:

  • getName() - возвращает уникальное имя данной реализации

  • format() - преобразовывает переданное значение в строку

  • parse() - преобразовывает строку в значение нужного типа

Datatype определяет два набора методов для форматирования/парсинга: с учетом локали и без учета локали. Преобразование с учетом локали используется повсеместно в пользовательском интерфейсе, преобразование без учета локали используется в системных механизмах, например, для сериализации в REST API.

Форматы для преобразований без учета локали задаются в вышеупомянутом файле datatypes.xml .

Форматы для преобразований с учетом локали задаются в главном пакете локализованных сообщений, в строках со следующими ключами:

  • numberDecimalSeparator - задает символ разделителя целой и дробной части для числовых типов

  • numberGroupingSeparator - задает символ разделителя групп разрядов для числовых типов

  • integerFormat - формат для типов Integer и Long

  • doubleFormat - формат для типа Double

  • decimalFormat - формат для типа BigDecimal

  • dateTimeFormat - формат для типа java.util.Date

  • dateFormat - формат для типа java.sql.Date

  • timeFormat - формат для типа java.sql.Time

  • trueString - строка, соответствующая Boolean.TRUE

  • falseString - строка, соответствующая Boolean.FALSE

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

4.2.2.3.1. Пример форматирования даты в UI

Рассмотрим отображение атрибута Order.date в таблице браузера заказов.

order-browse.xml

<table id="ordersTable">
  ...
  <columns>
      <column id="date"/>
      ...

Атрибут date в классе Order определен с типом "дата":

@Column(name = "DATE", nullable = false)
@Temporal(TemporalType.DATE)
private Date date;

Если текущий пользователь зарегистрирован c русской локалью, то из главного пакета локализованных сообщений клиентского уровня, из файла messages_ru.properties извлекается строка:

dateFormat=dd.MM.yyyy

Результат: дата "6 августа 2012 года" конвертируется в строку "06.08.2012" для отображения в ячейке таблицы.

4.2.2.3.2. Примеры форматирования дат и чисел в коде приложения
  • Пример форматирования даты

    @Inject
    protected UserSessionSource userSessionSource;
    ...
    Date date = ...;
    String dateStr = Datatypes.get(Date.class).format(date, userSessionSource.getLocale());
  • Пример форматирования числового значения с повышенной точностью (5 знаков после запятой) в блоке Web Client

    /com/sample/sales/web/messages_ru.properties

    coordinateFormat = #,##0.00000

    SomeClass.java

    @Inject
    protected Messages messages;
    @Inject
    protected UserSessionSource userSessionSource;
    ...
    String coordinateFormat = messages.getMainMessage("coordinateFormat");
    FormatStrings formatStrings = Datatypes.getFormatStrings(userSessionSource.getLocale());
    NumberFormat format = new DecimalFormat(coordinateFormat, formatStrings.getFormatSymbols());
    
    String formattedValue = format.format(value);
4.2.2.3.3. Пример специализированного Datatype

Рассмотрим реализацию нестандартного типа GeoCoordinateDatatype, предназначенного для атрибутов, хранящих географические координаты.

Создаем класс в модуле global:

public class GeoCoordinateDatatype extends DoubleDatatype {

  public static final String NAME = "geocoordinate";

  // формат общий для всех локалей, отличаться могут только символы десятичной точки
  public static final String FORMAT = "#0.000000";

  public GeoCoordinateDatatype(Element element) {
      super(element);
  }

  @Override
  public String getName() {
      return NAME;
  }

  @Override
  public String format(Double value, Locale locale) {
      if (value == null)
          return "";
      FormatStrings formatStrings = Datatypes.getFormatStrings(locale);
      if (formatStrings == null)
          return format(value); // FormatStrings для локали не определены, форматируем по данным datatypes.xml

      NumberFormat format = new DecimalFormat(FORMAT, formatStrings.getFormatSymbols());
      return format.format(value);
  }

  @Override
  public Double parse(String value, Locale locale) throws ParseException {
      if (StringUtils.isBlank(value))
          return null;
      FormatStrings formatStrings = Datatypes.getFormatStrings(locale);
      if (formatStrings == null)
          return parse(value); // FormatStrings для локали не определены, парсим по данным datatypes.xml

      NumberFormat format = new DecimalFormat(FORMAT, formatStrings.getFormatSymbols());
      return parse(value, format).doubleValue();
  }
}

Создаем файл datatypes.xml в корне каталога src модуля global проекта приложения и копируем в него все из файла /com/haulmont/chile/core/datatypes/datatypes.xml, расположенного в модуле global базового проекта cuba. Затем добавляем в него регистрацию нового типа:

<datatypes>

  <datatype class="com.sample.sales.entity.GeoCoordinateDatatype"
            format="#0.000000" decimalSeparator="." groupingSeparator=""/>
...

Указываем новый тип данных для требуемых атрибутов:

@MetaProperty(datatype = GeoCoordinateDatatype.NAME)
@Column(name = "LATITUDE")
private Double latitude;

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

4.2.2.4. Мета-аннотации

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

Обращение к мета-аннотациям производится с помощью метода мета-класса getAnnotations().

Источниками мета-аннотаций сущности являются:

  • Аннотации @OnDelete, @OnDeleteInverse, @Extends. При этом в мета-аннотациях создаются служебные объекты связей между сущностями.

  • Аннотации @NamePattern, @SystemLevel, @EnableRestore, @TrackEditScreenHistory. При этом создаются мета-аннотации с ключами, соответствующими полному имени класса Java аннотации.

  • Опционально: в прикладном проекте могут быть определены свои аннотации для сущностей, и в переопределенном методе MetadataImpl.initMetaAnnotations() отображены в соответствующие мета-аннотации.

  • Опционально: в файлах metadata.xml также могут быть определены мета-аннотации сущностей. Если мета-аннотация в XML имеет то же имя, что и мета-аннотация, созданная по Java аннотации класса сущности, первая переопределит значение второй.

    Пример определения мета-аннотаций в metadata.xml :

    <annotations>
      <entity class="com.haulmont.cuba.security.entity.User">
          <annotation name="com.haulmont.cuba.core.entity.annotation.TrackEditScreenHistory" value="false"/>
          <annotation name="com.haulmont.cuba.core.entity.annotation.EnableRestore" value="true"/>
      </entity>
    </annotations>

4.2.3. Представления

При извлечении сущностей из базы данных обычно встает вопрос - как обеспечить загрузку связанных сущностей на нужную глубину?

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

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

Другой похожей проблемой является ограничение набора локальных атрибутов сущностей загружаемого графа: например, некоторая сущность имеет 50 атрибутов, в том числе BLOB, а в экране отображается только 10 атрибутов. Зачем загружать из БД, затем сериализовать и передавать клиенту 40 атрибутов, которые ему в данный момент не нужны?

Механизм представлений (views) решает эти проблемы, обеспечивая извлечение из базы данных и передачу клиенту графов сущностей, ограниченных в глубину и по атрибутам. Представление является описателем графа объектов, который требуется в некотором экране UI или другом процессе обработки данных.

Обработка представлений производится следующим образом:

  • Все связи в модели данных объявляются с признаком загрузки по требованию (fetch = FetchType.LAZY, см. Раздел 4.2.1.2, «Аннотации сущностей»).

  • В процессе загрузки данных через DataManager клиентский код помимо JPQL запроса указывает нужное представление.

  • На основе представления формируется так называемый Fetch Plan - особенность лежащего в основе слоя ORM фреймворка Apache OpenJPA. Fetch Plan влияет на формирование SQL запроса к базе данных: как на список возвращаемых полей, так и на соединения с другими таблицами, содержащими связанные сущности.

  • В представлении некоторые ссылочные атрибуты могут быть объявлены как lazy (см. ниже). Lazy-атрибуты не включаются в Fetch Plan, а загружаются отдельными SQL запросами (иногда это полезно для упрощения основного SQL запроса). Для этого механизм обработки представлений просто обращается к соответствующим методам чтения атрибутов.

  • В результате на момент завершения транзакции, загружающей данные, в памяти Middleware содержится граф объектов, заданный JPQL запросом и представлением.

Рисунок 11. Классы представления

Классы представления

Представление определяется экземпляром класса View, в котором:

  • entityClass - класс сущности, для которого определено представление. Другими словами, "корень" дерева загружаемых сущностей.

  • name - имя представления. Должно быть либо null, либо уникальным в пределах данной сущности.

  • properties - коллекция экземпляров класса ViewProperty, соответствующих загружаемым атрибутам сущности.

  • includeSystemProperties - признак включения системных атрибутов (входящих в состав базовых интерфейсов персистентных сущностей BaseEntity и Updatable). Системные атрибуты не перечисляются в properties явно, а учитываются механизмом обработки представлений в зависимости от того, какие интерфейсы реализует данная сущность.

Класс ViewProperty имеет следующие свойства:

  • name - имя атрибута сущности

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

  • lazy - для ссылочных атрибутов признак того, что данный атрибут нужно не включать в Fetch Plan, а загружать отдельным SQL запросом, инициированным обращением к атрибуту. Следует иметь в виду, что при использовании DataManager и источников данных атрибут в любом случае будет загружен, данный признак влияет только на способ загрузки. Если же представление с lazy атрибутами используется на уровне ORM, то после загрузки экземпляров их обязательно нужно передать в метод EntityManager.fetch() до окончания транзакции, иначе lazy атрибуты загружены не будут.

Независимо от набора атрибутов, определенного в представлении, всегда загружаются следующие атрибуты:

  • id - идентификатор сущности

  • version - для оптимистично блокируемых сущностей, реализующих Versioned

  • deleteTs, deletedBy - для сущностей, реализующих SoftDelete

Незагруженные атрибуты имеют значение null. По умолчанию попытка установки значения незагруженного атрибута (вызов setter) для Detached сущности вызывает исключение. Это поведение можно изменить с помощью свойства приложения cuba.allowSetNotLoadedAttributes . Если данное свойство установлено в true, то вызов setter не приведет к исключению, но значение все равно сохранено не будет.

Следует иметь в виду, что незагруженные ссылочные атрибуты Detached сущности, соответствующие внешним ключам (т.е. ManyToOne, OneToOne), можно установить в новое ненулевое значение в любом случае, и изменения будут сохранены при последующем merge().

4.2.3.1. Создание представлений

Представление может быть создано двумя путями:

  • программно - созданием экземпляра View, например:

    View view = new View(Order.class)
          .addProperty("date")
          .addProperty("amount")
          .addProperty("customer", new View(Customer.class)
              .addProperty("name")
          );

    Как правило, таким способом создаются представления, используемые только в каком-то одном месте бизнес-логики.

  • декларативно - путем создания описателя на XML и его развертывания в репозитории представлений ViewRepository. При развертывании на основе XML-описателя создаются и кэшируются экземпляры View. В дальнейшем в любом месте кода приложения требуемое представление можно получить вызовом репозитория с указанием класса сущности и имени представления.

Рассмотрим подробнее декларативный способ создания и работы с представлениями.

ViewRepository является бином Spring, доступным для всех блоков приложения. Ссылка на ViewRepository может быть также получена через интерфейс инфраструктуры Metadata . Для получения экземпляра View, содержащегося в репозитории, используются методы getView(). Для развертывания XML-описателей представлений в репозитории используются методы deployViews() базовой реализации AbstractViewRepository.

В репозитории для каждой сущности по умолчанию доступны два представления с именами _local и _minimal:

  • _local включает в себя все локальные атрибуты сущности

  • _minimal включает в себя атрибуты, входящие в имя экземпляра сущности, и задаваемые аннотацией @NamePattern . Если аннотация @NamePattern для сущности не указана, данное представление не включает никаких атрибутов.

Подробная структура XML-описателей изложена в Раздел A.11, «views.xml»

Пример описателя представления для сущности Заказ, которое должно обеспечить загрузку всех локальных атрибутов, ассоциированного Покупателя и коллекции Пунктов заказа:

<view class="com.sample.sales.entity.Order"
    name="orderWithCustomer"
    extends="_local">
  <property name="customer" view="_minimal"/>
  <property name="items" view="itemsInOrder"/>
</view>

Рекомендуемый способ группировки и развертывания описателей представлений:

  • В модуле global в корне src создать файл views.xml и поместить в него все описатели представлений, которые должны быть доступны глобально, т.е. на всех уровнях приложения.

  • Зарегистрировать данный файл в свойстве cuba.viewsConfig блока Middleware и используемых клиентских блоков, т.е. в файле app.properties модуля core, в файле web-app.properties модуля web и так далее. Это обеспечит автоматическое развертывание представлений на старте приложения в репозитории Middleware и клиентских блоков (см. метод AbstractViewRepository.init()).

  • Если существуют представления, которые необходимы только какому-то одному клиентскому блоку приложения, то можно определить их в аналогичном файле данного блока, например, web-views.xml, и добавить этот файл в свойство cuba.viewsConfig этого блока, т.е. в данном случае в файл web-app.properties.

Если на момент развертывания некоторого представления в репозитории уже есть представление для этого же класса сущности и с таким же именем, то новое будет проигнорировано. Для того чтобы представление заменило имеющееся в репозитории и гарантированно было развернуто, в XML-описателе должен быть явно указан атрибут overwrite = "true".

Рекомендуется давать представлениям "описательные" имена. Например, не "browse", а "customerBrowse". Это упрощает поиск XML-описателей представлений по имени в процессе разработки приложения.

4.2.4. Управляемые бины

Управляемые бины (Managed Beans) − это программные компоненты, предназначенные для реализации бизнес-логики приложения. Термин "управляемые" в данном случае означает, что созданием экземпляров и установкой связей между такими компонентами управляет контейнер, который является основной частью фреймворка Spring.

Managed Bean представляет собой singleton, то есть в некотором блоке приложения существует только один экземпляр данного класса. Поэтому, если бин содержит изменяемые данные в полях (другими словами, имеет состояние), то обращение к таким данным необходимо синхронизировать.

4.2.4.1. Создание бина

Для создания управляемого бина достаточно добавить классу Java аннотацию @javax.annotation.ManagedBean. Например:

package com.sample.sales.core;

import com.sample.sales.entity.Order;
import javax.annotation.ManagedBean;

@ManagedBean(OrderWorker.NAME)
public class OrderWorker {
  public static final String NAME = "sales_OrderWorker";

  public void calculateTotals(Order order) {
  }
}

Рекомендуется присваивать бину уникальное имя вида {имя_проекта}_{имя_класса}, и определять его в константе NAME.

Класс управляемого бина должен находиться внутри дерева пакетов с корнем, заданным в элементе context:component-scan файла spring.xml . В нашем случае файл spring.xml содержит элемент:

<context:component-scan base-package="com.sample.sales"/>

что означает, что поиск аннотированных бинов для данного блока приложения будет происходить начиная с пакета com.sample.sales.

Если нужно обеспечить возможность подмены реализации, рекомендуется выделять бизнес-интерфейс бина, например, следующим образом:

package com.sample.sales.core;

import com.sample.sales.entity.Order;

public interface OrderWorker {
  String NAME = "sales_OrderWorker";

  void calculateTotals(Order order);
}
package com.sample.sales.core;

import com.sample.sales.entity.Order;
import javax.annotation.ManagedBean;

@ManagedBean(OrderWorker.NAME)
public class OrderWorkerBean implements OrderWorker {
  @Override
  public void calculateTotals(Order order) {
  }
}

Управляемые бины можно создавать на любом уровне, так как контейнер Spring Framework используется во всех стандартных блоках приложения.

4.2.4.2. Использование бина

Ссылку на бин можно получить с помощью инжекции или класса AppBeans. В качестве примера использования бина рассмотрим реализацию сервиса OrderService, делегирующего выполнение бину OrderWorker:

package com.sample.sales.core;

import com.haulmont.cuba.core.Persistence;
import com.sample.sales.entity.Order;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import javax.inject.Inject;

@Service(OrderService.NAME)
public class OrderServiceBean implements OrderService {

  @Inject
  protected Persistence persistence;

  @Inject
  protected OrderWorker orderWorker;

  @Transactional
  @Override
  public BigDecimal calculateTotals(Order order) {
      Order entity = persistence.getEntityManager().merge(order);
      orderWorker.calculateTotals(entity);
  }
}

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

4.2.5. JMX-бины

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

Рисунок 12.


Как видно из диаграммы, JMX-бин состоит из интерфейса и класса реализации. Класс должен представлять собой управляемый бин, то есть иметь аннотацию @ManagedBean и уникальное имя. Интерфейс JMX-бина специальным образом регистрируется в spring.xml для создания в текущей JVM собственно JMX-интерфейса.

Вызовы всех методов интерфейса JMX-бина перехватываются с помощью Spring AOP классом−интерцептором MBeanInterceptor, который обеспечивает установку правильного ClassLoader в контексте потока выполнения, и журналирование необработанных исключений.

Интерфейс JMX-бина обязательно должен иметь имя вида {имя_класса}MBean.

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

4.2.5.1. Создание JMX-бина

Рассмотрим процесс создания JMX-бина на примере.

  • Интерфейс JMX-бина:

    package com.sample.sales.core;
    
    import org.springframework.jmx.export.annotation.*;
    
    @ManagedResource(description = "Performs operations on Orders")
    public interface OrdersMBean {
    
      @ManagedOperation(description = "Recalculates an order amount")
      @ManagedOperationParameters({@ManagedOperationParameter(name = "orderId", description = "")})
      String calculateTotals(String orderId);
    }

    Интерфейс и его методы могут содержать аннотации для задания описания JMX-бина и его операций. Это описание будет отображаться во всех инструментах, работающих с данным JMX-интерфейсом, тем самым помогая администратору системы.

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

  • Класс JMX-бина:

    package com.sample.sales.core;
    
    import com.haulmont.cuba.core.*;
    import com.haulmont.cuba.core.app.*;
    import com.sample.sales.entity.Order;
    import org.apache.commons.lang.exception.ExceptionUtils;
    import javax.annotation.ManagedBean;
    import javax.inject.Inject;
    import java.util.UUID;
    
    @ManagedBean("sales_OrdersMBean")
    public class Orders implements OrdersMBean {
    
      @Inject
      protected OrderWorker orderWorker;
    
      @Inject
      protected Persistence persistence;
    
      @Authenticated
      @Override
      public String calculateTotals(final String orderId) {
          try {
              persistence.createTransaction().execute(new Transaction.Runnable() {
                  @Override
                  public void run(EntityManager em) {
                      Order entity = em.find(Order.class, UUID.fromString(orderId));
                      orderWorker.calculateTotals(entity);
                  }
              });
              return "Done";
          } catch (Throwable e) {
              return ExceptionUtils.getStackTrace(e);
          }
      }
    }

    Аннотация @ManagedBean определяет, что данный класс является управляемым бином с именем sales_OrdersMBean. Имя указано напрямую в аннотации, а не в константе, так как доступ к JMX-бину из кода Java не требуется.

    Рассмотрим реализацию метода calculateTotals().

    • Метод имеет аннотацию @Authenticated, т.е. при входе в метод и при отсутствии в потоке выполнения пользовательской сессии выполняется системная аутентификация.

    • Тело метода обернуто в блок try/catch, так что метод в случае успешного выполнения возвращает строку "Done", а в случае ошибки - stacktrace исключения в виде строки.

      Следует иметь в виду, что в данном случае все исключения обрабатываются, а значит, не попадают в MBeanInterceptor и не выводятся в журнал автоматически. Поэтому при необходимости логгировать исключения здесь нужно добавить вызов логгера в секции catch.

    • Логика метода заключается в том, что он стартует транзакцию, загружает экземпляр сущности Order по идентификатору, и передает управление бину OrderWorker для обработки.

  • Регистрация JMX-бина в spring.xml:

    <bean id="sales_MBeanExporter" lazy-init="false"
        class="com.haulmont.cuba.core.sys.jmx.MBeanExporter">
      <property name="beans">
          <map>
              <entry key="${cuba.webContextName}.sales:type=Orders"
                     value-ref="sales_OrdersMBean"/>
          </map>
      </property>
    </bean>

Все JMX-бины проекта объявляются в одном экземпляре MBeanExporter в элементах map/entry свойства beans. Ключом элемента здесь является JMX ObjectName, значением - имя бина, заданное в аннотации @ManagedBean. ObjectName начинается с имени веб-приложения, так как в одном экземпляре Tomcat (т.е. в одной JVM) может быть развернуто несколько веб-приложений, экспортирующих одинаковые JMX-интерфейсы.

4.2.5.2. JMX-бины платформы

В данном разделе описаны некоторые имеющиеся в платформе JMX-бины.

4.2.5.2.1. CachingFacadeMBean

CachingFacadeMBean предоставляет методы очистки различных кэшей в блоках Middleware и Web Client.

JMX ObjectName: app-core.cuba:type=CachingFacade и app.cuba:type=CachingFacade

4.2.5.2.2. ConfigStorageMBean

ConfigStorageMBean позволяет просматривать и задавать значения свойствам приложения в блоках Middleware, Web Client и Web Portal.

Данный интерфейс имеет отдельные наборы методов для работы с параметрами конфигурации и развертывания (*AppProperties) и с параметрами времени выполнения (*DbProperties), что обусловлено различием механизмов хранения этих категорий свойств.

Существуют следующие ограничения в использовании интерфейса ConfigStorageMBean:

  • Отображаются только явно установленные в месте хранения свойства. Если значение свойства не задано, то в случае обращения к нему из кода программы через конфигурационный интерфейс, возвращается значение по умолчанию. Однако через ConfigStorageMBean значение по умолчанию не может быть получено.

  • Измененные значения для свойств, хранящихся в файлах, не сохраняются, и действуют только до рестарта данного блока.

JMX ObjectName: app-core.cuba:type=ConfigStorage, app.cuba:type=ConfigStorage, app-portal.cuba:type=ConfigStorage

4.2.5.2.3. EmailerMBean

EmailerMBean позволяет просмотреть текущие значения параметров отсылки email, а также отправить тестовое сообщение.

JMX ObjectName: app-core.cuba:type=Emailer

4.2.5.2.4. PersistenceManagerMBean

PersistenceManagerMBean предоставляет следующие возможности:

  • управление механизмом статистики сущностей

  • отображение новых скриптов обновления БД методом findUpdateDatabaseScripts() и запуск обновления методом updateDatabase()

  • запуск произвольных JPQL запросов в контексте Middleware методами jpqlLoadList(), jpqlExecuteUpdate()

JMX ObjectName: app-core.cuba:type=PersistenceManager

4.2.5.2.5. ScriptingManagerMBean

ScriptingManagerMBean является JMX-фасадом для интерфейса инфраструктуры Scripting .

JMX ObjectName: app-core.cuba:type=ScriptingManager

JMX атрибуты:

JMX операции:

  • runGroovyScript() - выполнить скрипт Groovy в контексте Middleware и вернуть результат. В скрипт передаются следующие переменные:

    Для отображения в JMX-интерфейсе результат должен быть типа String. В остальном аналогичен методу Scripting.runGroovyScript().

    Пример скрипта, создающего набор тестовых пользователей:

    import com.haulmont.cuba.core.*
    import com.haulmont.cuba.core.global.*
    import com.haulmont.cuba.security.entity.*
    
    PasswordEncryption passwordEncryption = AppBeans.get(PasswordEncryption.class)
    
    Transaction tx = persistence.createTransaction()
    try {
      EntityManager em = persistence.getEntityManager()
      Group group = em.getReference(Group.class, UUID.fromString('0fa2b1a5-1d68-4d69-9fbd-dff348347f93'))
      for (i in (1..250)) {
          User user = new User()
          user.setGroup(group)
          user.setLogin("user_${i.toString().padLeft(3, '0')}")
          user.setName(user.login)
          user.setPassword(passwordEncryption.getPasswordHash(user.id, '1'));
          em.persist(user)
      }
      tx.commit()
    } finally {
      tx.end()
    }
4.2.5.2.6. ServerInfoMBean

ServerInfoMBean предоставляет общую информацию о данном блоке Middleware: номер и дату сборки, идентификатор сервера.

JMX ObjectName: app-core.cuba:type=ServerInfo

4.2.6. Интерфейсы инфраструктуры

Интерфейсы инфраструктуры обеспечивают доступ к часто используемой функциональности платформы. Большинство из этих интерфейсов расположены в модуле global и могут быть использованы как на среднем слое, так и в блоках клиентского уровня, но некоторые (например, Persistence ) доступны только коду среднего слоя.

Интерфейсы инфраструктуры реализуются бинами Spring Framework, поэтому они могут быть инжектированы в любые другие управляемые компоненты (Managed Beans, сервисы среднего слоя, контроллеры экранов универсального пользовательского интерфейса.

Кроме того, как и любые другие бины, интерфейсы инфраструктуры могут быть получены с помощью статических методов класса AppBeans, и использоваться в неуправляемых компонентах (POJO, вспомогательных классах и пр.).

4.2.6.1. Configuration

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

Пример:

String tempDir = AppBeans.get(Configuration.class).getConfig(GlobalConfig.class).getTempDir();

4.2.6.2. Messages

Интерфейс Messages обеспечивает получение локализованных строк сообщений.

Рассмотрим методы интерфейса подробнее.

  • getMessage() - возвращает локализованное сообщение по ключу, имени пакета сообщений и требуемой локали. Существует несколько модификаций данного метода в зависимости от набора параметров. Если локаль не указана в параметре метода, используется локаль текущего пользователя.

    Примеры:

    @Inject
    protected Messages messages;
    ...
    String message1 = messages.getMessage(getClass(), "someMessage");
    String message2 = messages.getMessage("com.abc.sales.web.customer", "someMessage");
    String message3 = messages.getMessage(RoleType.STANDARD);
  • formatMessage() - находит локализованное сообщение по ключу, имени пакета сообщений и требуемой локали, и использует его для форматирования переданных параметров. Формат задается по правилам метода String.format(). Существует несколько модификаций данного метода в зависимости от набора параметров. Если локаль не указана в параметре метода, используется локаль текущего пользователя.

    Пример:

    String formattedValue = messages.formatMessage(getClass(), "someFormat", someValue);
  • getMainMessage() - возвращает локализованное сообщение из главного пакета данного блока приложения.

    Пример:

    protected Messages messages = AppBeans.get(Messages.class);
    ...
    messages.getMainMessage("actions.Ok");
  • getMainMessagePack() - возвращает имя главного пакета сообщений данного блока приложения.

    Пример:

    String formattedValue = messages.formatMessage(messages.getMainMessagePack(), "someFormat", someValue);
  • getTools() - возвращает экземпляр интерфейса MessageTools (см. ниже).

4.2.6.2.1. MessageTools

ManagedBean, содержащий вспомогательные методы работы с локализованными сообщениями. Интерфейс MessageTools можно получить либо методом Messages.getTools(), либо как любой другой бин - инжекцией или через класс AppBeans.

Методы MessageTools:

  • loadString() - возвращает локализованное сообщение, заданное ссылкой вида msg://{messagePack}/{key}.

    Составные части ссылки:

    • msg:// - обязательный префикс.

    • {messagePack} - необязательное имя пакета сообщения. Если не указано, предполагается, что имя пакета передается в loadString() отдельным параметром.

    • {key} - ключ сообщения в пакете.

    Примеры ссылок на сообщения:

    msg://someMessage
    msg://com.abc.sales.web.customer/someMessage
  • getEntityCaption() - возвращает локализованное название сущности.

  • getPropertyCaption() - возвращает локализованное название атрибута сущности.

  • hasPropertyCaption() - определяет, задано ли для атрибута сущности локализованное название.

  • getLocValue() - возвращает локализованное значение атрибута сущности, основываясь на определении аннотации @LocalizedValue .

  • getMessageRef() - формирует для мета-свойства ссылку на сообщение, по которой можно получить локализованное название атрибута сущности.

  • getDefaultLocale() - возвращает локаль приложения по умолчанию, то есть указанную первой в списке свойства cuba.availableLocales .

  • useLocaleLanguageOnly() - возвращает true, если в списке поддерживаемых приложением локалей, заданном свойством cuba.availableLocales , для всех локалей определен только язык, а country и variant не указаны. Этим методом пользуются механизмы платформы, которым необходимо найти наиболее подходящую локаль из списка поддерживаемых на основе локали, полученной из внешних источников, таких как операционная система или HTTP запрос.

  • trimLocale() - удаляет из переданной локали все кроме языка, если метод useLocaleLanguageOnly() возвращает true.

Для расширения набора вспомогательных методов в конкретном приложении бин MessageTools можно переопределить. Примеры работы с расширенным интерфейсом:

MyMessageTools tools = messages.getTools();
tools.foo();
((MyMessageTools) messages.getTools()).foo();

4.2.6.3. Metadata

Интерфейс Metadata обеспечивает доступ к сессии метаданных и репозиторию представлений.

Методы интерфейса:

4.2.6.3.1. MetadataTools

ManagedBean, содержащий вспомогательные методы работы с метаданными. Интерфейс MetadataTools можно получить либо методом Metadata.getTools(), либо как любой другой бин - инжекцией или через класс AppBeans.

Методы MetadataTools:

  • getAllPersistentMetaClasses() - возвращает коллекцию мета-классов персистентных сущностей

  • getAllEmbeddableMetaClasses() - возвращает коллекцию мета-классов встраиваемых сущностей

  • getAllEnums() - возвращает коллекцию классов перечислений, используемых в качестве типов атрибутов сущностей

  • format() - форматирует переданное значение в соответствии с типом данных заданного мета-свойства

  • isSystem() - определяет, является ли переданное мета-свойство системным, т.е. заданным в одном из базовых интерфейсов сущностей

  • isPersistent() - определяет, является ли переданное мета-свойство персистентным, т.е. хранимым в БД

  • isTransient() - определяет, является ли переданное мета-свойство или произвольный атрибут неперсистентным

  • isEmbedded() - определяет, является ли переданное мета-свойство встроенным объектом

  • isAnnotationPresent() - определяет наличие указанной аннотации на классе или его предках

  • getNamePatternProperties() - возвращает коллекцию мета-свойств атрибутов, входящих в имя экземпляра, возвращаемого методом Instance.getInstanceName(). См. @NamePattern .

Для расширения набора вспомогательных методов в конкретном приложении бин MetadataTools можно переопределить. Примеры работы с расширенным интерфейсом:

MyMetadataTools tools = metadata.getTools();
tools.foo();
((MyMetadataTools) metadata.getTools()).foo();

4.2.6.4. Resources

Обеспечивает загрузку ресурсов по следующим правилам:

  1. если указанное местонахождение представляет собой URL, ресурс загружается из этого URL;

  2. если указанное местонахождение начинается с префикса classpath:, ресурс загружается из classpath;

  3. если не URL и не начинается с classpath:, то:

    1. в каталоге конфигурации приложения ищется файл, используя указанное местонахождение как относительный путь. Если файл найден, ресурс загружается из него;

    2. если ресурс не найден на предыдущих этапах, он загружается из classpath.

На практике явное указание URL или префикса classpath: используется редко, т.е. обычно ресурсы загружаются либо из конфигурационного каталога, либо из classpath. Ресурс в конфигурационном каталоге замещает одноименный ресурс в classpath.

Методы Resources:

  • getResourceAsStream() - возвращает InputStream для указанного ресурса, либо null, если ресурс не найден. Поток должен быть закрыт после использования, например:

    @Inject
    protected Resources resources;
    ...
    InputStream stream = null;
    try {
      stream = resources.getResourceAsStream(resourceLocation);
      ...
    } finally {
      IOUtils.closeQuietly(stream);
    }

    Возможно использование "try with resources":

    try (InputStream stream = resources.getResourceAsStream(resourceLocation)) {
      ...
    }
  • getResourceAsString() - возвращает указанный ресурс в виде строки, либо null, если ресурс не найден

4.2.6.5. Scripting

Интерфейс Scripting позволяет динамически (т.е. во время работы приложения) компилировать и загружать классы Java и Groovy, а также выполнять скрипты и выражения на Groovy.

Методы Scripting:

  • evaluateGroovy() - выполняет выражение на Groovy и возвращает его результат.

    Свойство приложения cuba.groovyEvaluatorImport позволяет определить общий набор импортируемых классов, подставляемых в каждое выполняемое выражение. По умолчанию все стандартные блоки приложения импортируют класс PersistenceHelper .

    Скомпилированные выражения кэшируются, что значительно ускоряет повторное выполнение.

    Пример:

    @Inject
    protected Scripting scripting;
    ...
    Integer intResult = scripting.evaluateGroovy("2 + 2", new Binding());
    
    Binding binding = new Binding();
    binding.setVariable("instance", new User());
    Boolean boolResult = scripting.evaluateGroovy("return PersistenceHelper.isNew(instance)", binding);
  • runGroovyScript() - выполняет скрипт Groovy и возвращает его результат.

    Скрипт должен быть расположен либо в конфигурационном каталоге приложения, либо в classpath (текущая реализация Scripting поддерживает ресурсы classpath только внутри JAR-файлов). Скрипт в конфигурационном каталоге замещает одноименный скрипт в classpath.

    Путь к скрипту указывается с разделителями /, в начале пути символ / не требуется.

    Пример:

    @Inject
    protected Scripting scripting;
    ...
    Binding binding = new Binding();
    binding.setVariable("itemId", itemId);
    BigDecimal amount = scripting.runGroovyScript("com/abc/sales/CalculatePrice.groovy", binding);
  • loadClass() - загружает Java или Groovy класс, используя следующую последовательность действий:

    1. Если класс уже загружен, возвращает его.

    2. Ищет исходный текст Groovy (файл *.groovy) в каталоге конфигурации. Если найден, компилирует его, загружает и возвращает класс.

    3. Ищет исходный текст Java (файл *.java) в каталоге конфигурации. Если найден, компилирует его, загружает и возвращает класс.

    4. Ищет скомпилированный класс в classpath, если найден - загружает и возвращает его.

    5. Если ничего не найдено, возвращает null.

    Файлы исходных текстов Java и Groovy в каталоге конфигурации можно изменять во время работы приложения. При следующем вызове loadClass() соответствующий класс будет перекомпилирован и возвращен новый, однако существуют следующие ограничения:

    • нельзя изменять тип исходного текста с Groovy на Java

    • если существовал исходный текст Groovy, и был однажды скомпилирован, то удаление файла исходного текста не приведет к загрузке другого класса из classpath - будет по-прежнему возвращаться класс, скомпилированный из удаленного исходника.

    Пример:

    @Inject
    protected Scripting scripting;
    ...
    Class calculatorClass = scripting.loadClass("com.abc.sales.PriceCalculator");
  • getClassLoader() - возвращает ClassLoader, способный работать по правилам, описанным выше для метода loadClass().

Кэш скомпилированных классов можно очистить во время выполнения с помощью JMX-бина CachingFacadeMBean.

См. также Раздел 4.2.5.2.5, «ScriptingManagerMBean»

4.2.6.6. Security

Обеспечивает авторизацию - проверку прав пользователя на различные объекты системы. Перед вызовом соответствующих методов UserSession выполняется поиск исходного мета-класса сущности, что является важным при наличии расширений. Кроме методов, дублирующих методы UserSession, данный интерфейс имеет методы isEntityAttrReadPermitted() и isEntityAttrUpdatePermitted(), предназначенные для определения доступности пути к атрибуту с учетом доступности атрибутов и сущностей, входящих в этот путь.

Подробнее см. Раздел 4.2.10, «Аутентификация пользователей»

4.2.6.7. TimeSource

Обеспечивает получение текущего времени. Применение new Date() и т.п. в прикладном коде не рекомендуется.

Примеры:

@Inject
protected TimeSource timeSource;
...
Date date = timeSource.currentTimestamp();
long startTime = AppBeans.get(TimeSource.class).currentTimeMillis();

4.2.6.8. UserSessionSource

Обеспечивает получение объекта сессии текущего пользователя. Подробнее см. Раздел 4.2.10, «Аутентификация пользователей»

4.2.6.9. UuidSource

Обеспечивает получение значений UUID, в том числе для идентификаторов сущностей. Применение UUID.randomUUID() в прикладном коде не рекомендуется.

Для вызова из статического контекста можно использовать класс UuidProvider, который имеет также дополнительный метод fromString(), работающий быстрее, чем стандартный метод UUID.fromString().

4.2.6.10. DataManager

Интерфейс DataManager является универсальным средством для загрузки графов сущностей из базы данных, и для сохранения изменений, произведенных в detached экземплярах сущностей.

DataManager всегда стартует новую транзакцию и по завершении работы выполняет коммит, таким образом возвращая сущности в detached состоянии.

Методы DataManager:

  • load(), loadList() - загружает граф сущностей в соответствии с параметрами переданного объекта LoadContext.

    В LoadContext обязательно должен быть передан либо JPQL-запрос, либо идентификатор сущности. Если передано и то и другое, используется запрос, а идентификатор игнорируется.

    Правила создания запросов аналогичны описанным в Раздел 4.4.4.4, «Выполнение JPQL запросов». Отличием является то, что в запросе LoadContext могут быть использованы только именованные параметры, позиционные не поддерживаются.

    Методы load() и loadList() проверяют наличие у пользователя права EntityOp.READ на загружаемую сущность. Кроме того, при извлечении сущностей из БД накладываются ограничения групп доступа. Для отмены действия ограничений в текущем запросе можно передать в LoadContext атрибут useSecurityConstraints = false.

    Примеры загрузки сущностей в контроллере экрана:

    @Inject
    private DataManager dataManager;
    
    private Book loadBookById(UUID bookId) {
        LoadContext loadContext = new LoadContext(Book.class)
                .setId(bookId).setView("book.edit");
        return dataManager.load(loadContext);
    }
    
    private List<BookPublication> loadBookPublications(UUID bookId) {
        LoadContext loadContext = new LoadContext(BookPublication.class)
                .setView("bookPublication.full");
        loadContext.setQueryString("select p from library$BookPublication p where p.book.id = :bookId")
                .setParameter("bookId", bookId);
        return dataManager.loadList(loadContext);
    }

  • commit() - сохраняет в базе данных набор сущностей, переданный в объекте CommitContext. Отдельно указываются коллекции сущностей, которые нужно сохранить, и которые нужно удалить.

    Метод возвращает набор экземпляров сущностей, возвращенных из метода EntityManager.merge(), то есть по сути свежие экземпляры, только что обновленные в БД. Дальнейшая работа должна производиться именно с этими возвращенными экземплярами, чтобы предотвратить потерю данных или исключения оптимистичной блокировки. Для того, чтобы обеспечить наличие нужных атрибутов у возвращенных сущностей, с помощью мэп CommitContext.getViews() можно указать представление для каждого сохраняемого экземпляра.

    Метод commit() проверяет наличие у пользователя права EntityOp.UPDATE на изменяемые сущности, и EntityOp.DELETE на удаляемые.

    Примеры сохранения коллекций сущностей:

    @Inject
    private DataManager dataManager;
    
    private void saveBookInstances(List<BookInstance> toSave, List<BookInstance> toDelete) {
        CommitContext commitContext = new CommitContext(toSave, toDelete);
        dataManager.commit(commitContext);
    }
    
    private Set<Entity> saveAndReturnBookInstances(List<BookInstance> toSave, View view) {
        CommitContext commitContext = new CommitContext();
        for (BookInstance bookInstance : toSave) {
            commitContext.getCommitInstances().add(bookInstance);
            commitContext.getViews().put(bookInstance, view);
        }
        return dataManager.commit(commitContext);
    }

  • reload() - удобные методы для перезагрузки экземпляра сущности с требуемым представлением. Делегируют выполнение методу load().

  • remove() - удаляет экземпляр сущности из базы данных. Делегируют выполнение методу commit().

В процессе загрузки данных DataManager может реализовывать дополнительную функциональность, описанную ниже.

4.2.6.10.1. Запросы с distinct

В JPQL запросах для экранов со списками сущностей, в которых включено постраничное отображение и возможна непредсказуемая модификация запроса универсальным фильтром или механизмом ограничений групп доступа, при отсутствии в запросе оператора distinct может возникать следующий эффект:

  • при объединении с коллекцией на уровне извлечения из базы данных возникает набор с дубликатами строк

  • на клиентском уровне в источнике данных дубликаты исчезают, т.к. попадают в мэп (java.util.Map)

  • при постраничном отображении на одной странице оказывается меньшее количество строк, чем запрошено, общее количество строк наоборот завышено.

Таким образом, рекомендуется в JPQL запросы браузеров включать предложение distinct, которое гарантирует отсутствие дубликатов записей при выборке из базы данных. Однако в некоторых серверах БД (в частности PostgreSQL) при большом количестве извлекаемых записей (более 10000) SQL запрос с distinct выполняется недопустимо долго.

Для решения этой проблемы в платформе реализована возможность корректной работы без distinct на уровне SQL. Данный механизм включается свойством приложения cuba.inMemoryDistinct, при активации которого выполняется следующее:

  • В JPQL запросе должен по-прежнему присутствовать select distinct

  • В DataManager из JPQL запроса перед отправкой в ORM distinct вырезается

  • После загрузки страницы данных на Middleware удаляются дубликаты и выполняются дополнительные запросы к БД для получения нужного количества строк, которые затем и возвращаются клиенту.

4.2.6.10.2. Последовательная выборка

DataManager может выполнять последовательную выборку данных из результатов предыдущего запроса. Эта возможность используется в универсальном фильтре при последовательном наложении фильтров.

Данный механизм работает следующим образом:

  • При получении LoadContext с установленными атрибутами prevQueries и queryKey DataManager выполняет выборку по предыдущему запросу и сохраняет идентификаторы полученных сущностей в таблице SYS_QUERY_RESULT (соответствующей сущности sys$QueryResult), разделяя наборы записей по идентификаторам пользовательских сессий и ключу сеанса выборки queryKey.

  • Текущий запрос модифицируется для объединения с результатами предыдущего, так что в итоге возвращает данные, соответствующие условиям обоих запросов, объединенных по "И".

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

Таблицу SYS_QUERY_RESULT необходимо периодически чистить от ненужных результатов запросов, оставленных завершенными пользовательскими сессиями. Для этого предназначен метод deleteForInactiveSessions бина QueryResultsManagerAPI. В прикладном проекте с включенным параметром cuba.allowQueryFromSelected необходимо вызывать этот метод из назначенных заданий, например:

<task:scheduled-tasks scheduler="scheduler">
      <task:scheduled ref="cuba_QueryResultsManager" method="deleteForInactiveSessions" fixed-rate="600000"/>
  </task:scheduled-tasks>

4.2.7. AppContext

AppContext - системный класс, в статических полях которого хранятся ссылки на некоторые общие для любого блока приложения компоненты:

  • ApplicationContext фреймворка Spring

  • Набор свойств приложения, загруженных из файлов app.properties

  • ThreadLocal переменная, хранящая экземпляры SecurityContext

  • Коллекция слушателей жизненного цикла приложения (AppContext.Listener)

AppContext инициализируется на запуске приложения классами-загрузчиками, специфичными для типа блока приложения:

  • загрузчик Middleware - AppContextLoader

  • загрузчик Web Client - WebAppContextLoader

  • загрузчик Web Portal - PortalAppContextLoader

  • загрузчик Desktop Client - DesktopAppContextLoader

AppContext может быть использован в прикладном коде для решения следующих задач:

  • Регистрации слушателей, срабатывающих после полной инициализации и перед закрытием приложения, например:

    AppContext.addListener(new AppContext.Listener() {
      @Override
      public void applicationStarted() {
          System.out.println("Application is ready");
      }
    
      @Override
      public void applicationStopped() {
          System.out.println("Application is closing");
      }
    });

    В момент вызова applicationStarted():

    • Полностью инициализированы все бины, в том числе выполнены их методы @PostConstruct.

    • Можно использовать статические методы получения бинов AppBeans.get().

    • Метод AppContext.isStarted() возвращает true.

    • Метод AppContext.isReady() возвращает false.

    • В блоке Middleware: если свойство приложения cuba.automaticDatabaseUpdate включено, все скрипты обновления БД успешно выполнены.

    В момент вызова applicationStopped():

    • Все бины работоспособны и доступны через статические методы AppBeans.get().

    • Метод AppContext.isStarted() возвращает false.

    • Метод AppContext.isReady() возвращает false.

    Практический пример использования AppContext.Listener см. в Раздел 5.8.4, «Выполнение кода на старте приложения».

  • Получения значений свойств приложения, хранимых в файлах app.properties, если они недоступны через конфигурационные интерфейсы.

  • Передачи SecurityContext в новые потоки выполнения, см. Раздел 4.2.10, «Аутентификация пользователей».

Для получения ссылок на Spring-бины используйте инжекцию или статические методы класса AppBeans.

Использование AppContext.getApplicationContext().getBean() не рекомендуется.

4.2.8. Свойства приложения

Свойства приложения − именованные данные различных типов, определяющие всевозможные аспекты конфигурации и функционирования приложения.

По назначению свойства приложения можно классифицировать следующим образом:

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

    Например: cuba.springContextConfig, cuba.web.useLightHeader.

  • Параметры развертывания - различные URL для соединения блоков приложения, тип используемой БД, настройки подсистемы безопасности и т.д.

    Например: cuba.connectionUrlList, cuba.dbmsType, cuba.userSessionExpirationTimeoutSec .

  • Параметры времени выполнения - активность аудита, параметры отсылки email и т.д.

    Например: cuba.security.EntityLog.enabled, cuba.email.smtpHost.

Как правило, некоторое свойство принадлежит только одному или нескольким блокам приложения. Например, cuba.persistenceConfig имеет смысл только для Middleware, cuba.web.useLightHeader − только для Web Client, а cuba.springContextConfig − для всех блоков.

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

Принадлежность можно выяснить следующими способами:

4.2.8.1. Доступ к свойствам

Основной способ доступа к свойствам приложения из прикладного кода − использование механизма конфигурационных интерфейсов. Кроме того, все параметры конфигурации и развертывания доступны через методы класса AppContext .

Некоторые блоки приложения определяют JMX-интерфейсы для доступа к свойствам приложения. В частности, в блоках Middleware, Web Client и Web Portal имеется JMX-интерфейс ConfigStorageMBean , позволяющий получить и задать значение любого свойства во время работы приложения.

4.2.8.2. Хранение свойств в файлах

Свойства, определяющие конфигурацию и параметры развертывания, задаются в специальных файлах свойств, имеющих имя вида *-app.properties. Каждый блок приложения имеет набор таких файлов, включающий в себя файлы из базовых проектов платформы и файл текущего приложения. Набор файлов свойств определяется следующим образом:

  • Для блоков, являющихся веб-приложениями (Middleware, Web Client, Web Portal) набор файлов свойств задается в web.xml в параметре appPropertiesConfig.

  • Для блока Desktop Client основной способ задания набора файлов свойств − переопределение в приложении метода getDefaultAppPropertiesConfig() в классе-наследнике com.haulmont.cuba.desktop.App.

Например, набор файлов свойств блока Middleware проекта sales задается в файле web/WEB-INF/web.xml модуля core, и выглядит следующим образом:

classpath:cuba-app.properties
classpath:app.properties
file:${catalina.home}/conf/app-core/local.app.properties

Здесь префикс classpath: означает, что данный файл нужно искать в Java classpath, префикс file: − в файловой системе. Возможно использование системных свойств Java, в данном случае это catalina.home − путь к корню Tomcat.

Порядок перечисления файлов важен, так как значения, указанные в каждом последующем файле заменяют значения одноименных свойств, заданные в предыдущих файлах. Этим достигается переопределение свойств платформы в конкретном приложении.

Последний файл в приведенном наборе − local.app.properties. Он может использоваться для переопределения свойств приложения при развертывании. Если этого файла нет, он игнорируется. Если же во время инсталляции системы требуется переопределение некоторых параметров (как правило, различных URL), достаточно создать этот файл и поместить в него переопределяемые свойства. При последующих обновлениях системы такой файл с локальными настройками легко сохранить.

Аналогом local.app.properties для Desktop Client служат аргументы командной строки запуска JVM. Загрузчик свойств данного блока воспринимает все аргументы, содержащие знак "=", как пары ключ-значение, и заменяет ими соответствующие свойства приложения, заданные в файлах app.properties.

Правила задания информации в файлах *.properties:

  • Кодировка файла - UTF-8

  • Ключ может состоять из латинских букв, цифр, точек и знаков подчеркивания

  • Значение пишется после знака равно (=)

  • Значение не нужно брать в кавычки " или '

  • Файловые пути записываются либо в UNIX виде (/opt/haulmont/), либо в Windows виде (c:\\haulmont\\)

  • Возможно использование кодов \n \t \r. Символ \ является зарезервированным, для вставки в значение экранируется сам собой (\\). Подробнее см.: http://docs.oracle.com/javase/tutorial/java/data/characters.html

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

4.2.8.3. Хранение свойств в базе данных

Параметры времени выполнения хранятся в таблице SYS_CONFIG базы данных.

Такие свойства имеют следующие особенности:

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

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

  • значение свойства может быть переопределено для конкретного блока приложения в его файле app.properties. Поиск значения всегда происходит в два этапа - сначала в app.properties, если не найдено - то в базе данных. Поэтому изменять значение нужно в обоих местах хранения.

Хранящиеся в БД свойства кэшируются на уровне Middleware. Очистить кэш можно с помощью JMX-интерфейсов ConfigStorageMBean методом clearCache() или CachingFacadeMBean методом clearConfigStorageCache().

Следует иметь в виду, что на клиентском уровне чтение свойства, хранящегося в БД, приводит к запросу к Middleware, что менее эффективно, чем чтение локального свойства из app.properties. Для уменьшения количества таких запросов клиент кэширует все свойства, хранящиеся в БД, на время жизни экземпляра реализации конфигурационного интерфейса. Поэтому если, например, в некотором экране UI необходимо несколько раз обратиться к свойствам одного конфигурационного интерфейса, лучше получить ссылку на него при инициализации экрана, и сохранить в поле для последующих обращений к одному и тому же экземпляру.

4.2.8.4. Конфигурационные интерфейсы

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

  • типизированность - прикладной код работает с нужными типами (String, Boolean, Integer и пр.), а не только со строками

  • в прикладном коде вместо строковых идентификаторов свойств используются методы интерфейсов, имена которых подсказываются средой разработки

Пример получения значения таймаута транзакции в блоке Middleware:

@Inject
private ServerConfig serverConfig;

public void doSomething() {
  int timeout = serverConfig.getDefaultQueryTimeoutSec();
  ...
}

При невозможности инжекции можно получить ссылку на конфигурационный интерфейс через Configuration:

int timeout = AppBeans.get(Configuration.class)
  .getConfig(ServerConfig.class)
  .getDefaultQueryTimeoutSec();

Конфигурационные интерфейсы не являются нормальными бинами Spring, не пытайтесь получить их через AppBeans.get() - только непосредственной инжекцией самого интерфейса или через Configuration.getConfig().

4.2.8.4.1. Использование

Для создания конфигурационного интерфейса необходимо:

  • Создать интерфейс, унаследованный от com.haulmont.cuba.core.config.Config (не путать с классом сущности com.haulmont.cuba.core.entity.Config)

  • Добавить интерфейсу аннотацию @Source для указания источника (способа хранения) параметров:

    • SourceType.SYSTEM - значение свойства будет взято из системных свойств данной JVM, т.е. методом System.getProperty()

    • SourceType.APP - значение свойства будет взято из файлов app.properties

    • SourceType.DATABASE - значение свойства будет взято из таблицы SYS_CONFIG

  • Создать методы доступа к свойству (getter / setter). Если значение свойства не предполагается изменять во время выполнения, метод доступа на запись не нужен. Возможный тип свойства рассмотрен ниже.

  • Добавить методу доступа на чтение аннотацию @Property, определяющую имя свойства.

  • Опционально аннотацию @Source можно задать для отдельного свойства в интерфейсе, если его источник отличается от заданного для всего интерфейса.

Например:

@Source(type = SourceType.DATABASE)
public interface SalesConfig extends Config {

  @Property("sales.companyName")
  String getCompanyName();
}

Создавать класс реализации конфигурационного интерфейса не нужно - при получении ссылки на интерфейс через Configuration будет автоматически создан необходимый прокси-объект.

4.2.8.4.2. Типы свойств

Без дополнительных усилий поддерживаются следующие типы свойств:

  • String, простые типы либо их объектные обертки (boolean, Boolean, int, Integer, etc.).

  • Перечисления (enum). Значение свойства сохраняется в файле или БД в виде имени значения перечисления.

    Если перечисление реализует интерфейс EnumClass и имеет статический метод fromId() для получения значения по идентификатору, с помощью аннотации @EnumStore можно задать хранение значения в виде идентификатора. Например:

    @Property("myapp.defaultCustomerGrade")
    @DefaultInteger(10)
    @EnumStore(EnumStoreMode.ID)
    CustomerGrade getDefaultCustomerGrade();
    
    @EnumStore(EnumStoreMode.ID)
    void setDefaultCustomerGrade(CustomerGrade grade);
  • Классы персистентных сущностей. При обращении к свойству типа сущности происходит загрузка из БД экземпляра, заданного значением свойства.

Для поддержки произвольного типа необходимо реализовать классы TypeStringify и TypeFactory для преобразования значения в строку и из нее, и указать эти классы для свойства с помощью аннотаций @Stringify и @Factory.

Рассмотрим этот процесс на примере типа UUID.

  • Создаем класс com.haulmont.cuba.core.config.type.UuidTypeFactory унаследованный от com.haulmont.cuba.core.config.type.TypeFactory и реализуем в нем метод:

    public Object build(String string) {
      if (string == null)
          return null;
      return UUID.fromString(string);
    }
  • TypeStringify создавать не нужно, т.к. по умолчанию будет использован метод toString() − в данном случае он нам подходит.

  • Аннотируем свойство в конфигурационном интерфейсе:

    @Factory(factory = UuidTypeFactory.class)
    UUID getUuidProp();
    void setUuidProp(UUID value);

В платформе определены реализации TypeFactory для следующих типов:

  • UUID - UuidTypeFactory, описано выше.

  • java.util.Date - DateFactory. Значение даты должно быть указано в формате yyyy-MM-dd HH:mm:ss.SSS, например:

    cuba.test.dateProp = 2013-12-12 00:00:00.000
  • List<Integer> (список целых чисел) - IntegerListTypeFactory. Значение свойства должно быть указано в виде списка чисел, разделенных пробелами, например:

    cuba.test.integerListProp = 1 2 3
  • List<String> (список строк) - StringListTypeFactory. Значение свойства должно быть указано в виде списка строк, разделенных символом "|", например:

    cuba.test.stringListProp = aaa|bbb|ccc
4.2.8.4.3. Значения по умолчанию

Для свойств конфигурационных интерфейсов могут быть заданы значения по умолчанию. Эти значения будут возвращаться вместо null, если данный параметр не задан в месте хранения - в БД или в app.properties.

Значение по умолчанию может быть задано в виде строки с помощью аннотации @Default, либо в виде конкретного типа с помощью других аннотаций пакета com.haulmont.cuba.core.config.defaults:

@Property("cuba.email.adminAddress")
@Default("address@company.com")
String getAdminAddress();

@Property("cuba.email.delayCallCount")
@Default("2")
int getDelayCallCount();

@Property("cuba.email.defaultSendingAttemptsCount")
@DefaultInt(10)
int getDefaultSendingAttemptsCount();

@Property("cuba.test.dateProp")
@Default("2013-12-12 00:00:00.000")
@Factory(factory = DateFactory.class)
Date getDateProp();

@Property("cuba.test.integerList")
@Default("1 2 3")
@Factory(factory = IntegerListTypeFactory.class)
List<Integer> getIntegerList();

@Property("cuba.test.stringList")
@Default("aaa|bbb|ccc")
@Factory(factory = StringListTypeFactory.class)
List<String> getStringList();

Для сущностей значение по умолчанию задается строкой вида {entity_name}-{id}-{optional_view_name}, например:

@Default("sec$User-98e5e66c-3ac9-11e2-94c1-3860770d7eaf-browse")
User getAdminUser();

@Default("sec$Role-a294aef0-3ac9-11e2-9433-3860770d7eaf")
Role getAdminRole();

4.2.9. Локализация сообщений

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

Возможности выбора языка пользователем определяются комбинацией свойств приложения cuba.localeSelectVisible и cuba.availableLocales.

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

Раздел 5.8.1, «Получение локализованных сообщений» содержит информацию о способах получения локализованных сообщений в различных компонентах системы.

4.2.9.1. Пакеты сообщений

Пакет сообщений представляет собой набор файлов свойств с именами вида messages{_XX}.properties, расположенных в одном Java-пакете. Суффикс XX определяет язык, для которого в данном файле содержатся сообщения, и соответствует коду языка в Locale.getLanguage(). Возможно также использование остальных атрибутов Locale, например, country. В этом случая файл пакета будет иметь вид messages{_XX_YY}.properties. Один из файлов пакета может быть без суффикса языка - это файл по умолчанию. Именем пакета сообщений считается имя Java-пакета, в котором расположены файлы пакета.

Рассмотрим пример:

/com/abc/sales/gui/customer/messages.properties
/com/abc/sales/gui/customer/messages_fr.properties
/com/abc/sales/gui/customer/messages_ru.properties

Данный пакет состоит из 3-х файлов - один для русского языка, один для французского, и один по умолчанию. Имя пакета - com.abc.sales.gui.customer

Файлы сообщений содержат пары ключ-значение, где ключ - это идентификатор сообщения, на который ссылается код приложения, а значение - само сообщение на языке данного файла. Правила задания пар аналогичны правилам файлов свойств java.util.Properties, со следующими особенностями:

  • Кодировка файла - обязательно UTF-8

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

    @include=com.haulmont.cuba.web, com.abc.sales.web
    
    someMessage=Some Message
    ...

Получение сообщений из пакетов производится с помощью методов интерфейса Messages по следующим правилам:

  • Сначала производится поиск в конфигурационном каталоге приложения

    • Ищется файл messages_XX.properties в каталоге, задаваемом именем пакета сообщений, где XX - код требуемого языка

    • Если такого файла нет, в этом же каталоге ищется файл по умолчанию messages.properties

    • Если найден или файл нужного языка, или файл по умолчанию, он загружается вместе со всеми @include, и в нем ищется ключ сообщения

    • Если файл не найден, либо нужный ключ в нем отсутствует, производится смена каталога на родительский, и процедура поиска повторяется. И так до достижения корня конфигурационного каталога.

  • Если в конфигурационном каталоге сообщение не найдено, производится поиск в classpath по такому же алгоритму.

  • На клиентском уровне, если сообщение не найдено на предыдущих шагах, отправляется запрос на Middleware, и сообщение ищется там аналогичным способом.

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

Рекомендуется организовывать пакеты сообщений следующим образом:

  • Если приложение не предполагает интернационализации, то можно не использовать пакеты и включать строки сообщений прямо в код приложения, либо пользоваться файлами по умолчанию messages.properties для отделения ресурсов от кода.

  • Если приложение интернациональное, логично файлы по умолчанию использовать для языка основной аудитории приложения, либо для английского языка. Именно сообщения из файлов по умолчанию будут показаны пользователю, если сообщений для нужного языка не найдено.

4.2.9.2. Главный пакет сообщений

Каждый стандартный блок приложения определяет для себя один главный пакет сообщений. Для блоков клиентского уровня этот пакет содержит названия пунктов главного меню и общих элементов UI (например, названия кнопок OK и Cancel). Для всех блоков приложения, включая Middleware, главный пакет определяет форматы преобразований Datatype .

Для указания главного пакета сообщений используется свойство приложения cuba.mainMessagePack . Значением свойства может быть либо один пакет, либо список пакетов, разделенный пробелами. Например:

cuba.mainMessagePack=com.haulmont.cuba.web com.abc.sales.web

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

4.2.9.3. Локализация названий сущностей и атрибутов

Для отображения в UI локализованных названий сущностей и их атрибутов необходимо создать специальные пакеты сообщений в тех же Java-пакетах, что и сами сущности. Формат файлов сообщений должен быть следующим:

  • Ключ названия сущности - простое имя класса (без пакета)

  • Ключ названия атрибута - простое имя класса, затем через точку имя атрибута

Пример русской локализации сущности com.abc.sales.entity.Customer - файл /com/abc/sales/entity/messages_ru.properties:

Customer=Покупатель
Customer.name=Имя
Customer.email=Email

Order=Заказ
Order.customer=Покупатель
Order.date=Дата
Order.amount=Сумма

Такие пакеты сообщений, как правило, используются неявно для разработчика, например, визуальными компонентами Table и FieldGroup . Кроме того, названия сущностей и атрибутов могут быть также получены следующими методами:

  • программно - методами MessageTools getEntityCaption(), getPropertyCaption()

  • в XML дескрипторе экрана - указанием ссылки на сообщение по правилам MessageTools.loadString(): msg://{entity_package}/{key}, например,

    caption="msg://com.abc.sales.entity/Customer.name"

4.2.9.4. Локализация enum

Для локализации названий и значений перечислений необходимо в пакет сообщений, находящийся в Java-пакете класса перечисления добавить сообщения со следующими ключами:

  • Ключ названия перечисления - простое имя класса (без пакета)

  • Ключ значения - простое имя класса, затем через точку имя значения

Например, для перечисления

package com.abc.sales;

public enum CustomerGrade { PREMIUM, HIGH, STANDARD }

файл русской локализации /com/abc/sales/messages_ru.properties должен содержать строки:

CustomerGrade=Уровень покупателя
CustomerGrade.PREMIUM=Премиум
CustomerGrade.HIGH=Высокий
CustomerGrade.STANDARD=Стандартный

Локализованные значения перечислений автоматически используются различными визуальными компонентами, например, LookupField . Для программного получения локализованного значения перечисления можно использовать метод getMessage() интерфейса Messages , просто передавая в него экземпляр enum.

4.2.10. Аутентификация пользователей

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

4.2.10.1. UserSession

Основной элемент подсистемы контроля доступа в CUBA-приложении - пользовательская сессия. Это объект класса UserSession, который ассоциирован с аутентифицированным в данный момент в системе пользователем, и содержит информацию о правах доступа пользователя к данным. Объект текущей сессии может быть получен в любом блоке приложения через интерфейс инфраструктуры UserSessionSource .

Пользовательская сессия создается на Middleware при выполнении метода LoginService.login() после аутентификации пользователя по переданному имени и паролю. Объект UserSession затем кэшируется в данном блоке Middleware, и возвращается на клиентский уровень. При работе в кластере объект сессии реплицируется на соседние узлы кластера Middleware. Клиентский блок, получив объект сессии, также сохраняет его у себя, так или иначе ассоциируя с активным пользователем (например, в HTTP сессии). Далее все вызовы Middleware для данного пользователя сопровождаются передачей идентификатора сессии (типа UUID), причем прикладному коду не нужно об этом заботиться - идентификатор сессии передается автоматически, независимо от сигнатуры вызываемых методов среднего слоя. Обработка вызовов клиентов на Middleware начинается с извлечения из кэша сессии по полученному идентификатору и установки ее в потоке выполнения. Объект сессии удаляется из кэша при вызове метода LoginService.logout(), либо при истечении времени бездействия, определяемого свойством приложения cuba.userSessionExpirationTimeoutSec .

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

Объект UserSession содержит также методы для авторизации текущего пользователя, т.е. проверки его прав на объекты системы: isScreenPermitted(), isEntityOpPermitted(), isEntityAttrPermitted(), isSpecificPermitted().

С объектом UserSession могут быть ассоциированы именованные атрибуты произвольного сериализуемого типа. Атрибуты устанавливаются методом setAttribute() и возвращаются методом getAttribute(). Последний может также возвращать следующие параметры сессии, как если бы они были атрибутами:

  • userId - ID текущего зарегистрированного или замещенного пользователя;

  • userLogin - логин текущего зарегистрированного или замещенного пользователя в нижнем регистре.

Атрибуты реплицируются в кластере Middleware так же, как и все остальные данные сессии.

4.2.10.2. Вход в систему

Стандартный вариант входа пользователя:

  • пользователь вводит свой логин и пароль

  • клиентский блок приложения хэширует пароль, вызывая метод getPlainHash() бина PasswordEncryption и вызывает на Middleware метод LoginService.login(), передавая ему логин пользователя и хэш пароля

  • LoginService делегирует выполнение бину LoginWorker, который загружает объект User по полученному логину, хэширует полученный хэш пароля повторно, используя в качестве соли идентификатор пользователя, и сравнивает полученный хэш с сохраненным в БД хэшем пароля. В случае несовпадения выбрасывается исключение LoginException.

  • После успешной аутентификации в созданный экземпляр UserSession загружаются все параметры доступа данного пользователя: список ролей, права, ограничения и атрибуты сессии.

Алгоритм хэширования паролей реализуется бином типа EncryptionModule и задается в свойстве приложения cuba.passwordEncryptionModule . По умолчанию - SHA-1.

Возможен вариант, когда пароль пользователя (точнее, хэш пароля) не хранится в базе данных, а проверяется внешними средствами, например, путем интеграции с ActiveDirectory. В этом случае фактически аутентификацию выполняет клиентский блок, а Middleware "доверяет" клиенту, создавая сессию по одному только логину пользователя без пароля методом LoginService.loginTrusted(). Метод loginTrusted() требует выполнения следующих условия:

  • клиентский блок должен передать так называемый доверенный пароль, задаваемый на Middleware и на клиентском блоке свойством приложения cuba.trustedClientPassword

  • IP адрес клиентского блока должен соответствовать маске, задаваемой свойством приложения cuba.trustedClientPermittedIpMask

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

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

Вход в систему для процессов внутри Middleware выполняется вызовом LoginWorker.loginSystem() с передачей логина пользователя (без пароля), от имени которого будет работать данный процесс. В результате создается объект UserSession , который будет закэширован в данном блоке Middleware и не будет реплицироваться в кластере.

Более подробно аутентификация процессов внутри Middleware рассмотрена в разделе Раздел 4.4.2, «Системная аутентификация»

4.2.10.3. SecurityContext

Экземпляр класса SecurityContext хранит информацию о пользовательской сессии для текущего потока выполнения. Он создается и передается в метод AppContext.setSecurityContext() в следующие моменты:

  • для блоков Web Client и Web Portal - в начале обработки каждого HTTP-запроса от пользовательского браузера

  • для блока Middleware - в начале обработки каждого запроса от клиентского уровня

  • для блока Desktop Client - один раз после входа пользователя, так как десктопное приложение является однопользовательским

По окончании выполнения запроса в первых двух случаях SecurityContext удаляется из потока выполнения.

При создании прикладным кодом нового потока выполнения в него необходимо передать текущий экземпляр SecurityContext, например:

final SecurityContext securityContext = AppContext.getSecurityContext();
executor.submit(new Runnable() {
  public void run() {
      AppContext.setSecurityContext(securityContext);
      // business logic here
  }
});

4.2.11. Обработка исключений

В данном разделе рассмотрены различные аспекты генерации и обработки исключений в CUBA-приложениях.

4.2.11.1. Классы исключений

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

  • Если исключение является нормальной частью бизнес-логики и при его возникновении требуется предпринимать некоторые нетривиальные действия, то класс исключения следует делать декларируемым (наследником Exception). Обработка таких исключений производится вызывающим кодом.

  • Если исключение сигнализирует об ошибочной ситуации, и реакцией на него должно быть прерывание хода выполнения и простое действие типа отображения информации об ошибке пользователю, то класс исключения следует делать недекларируемым (наследником RuntimeException). Обработка таких исключений производится специальными классами-обработчиками, зарегистрированными в клиентских блоках приложения.

  • Если исключение выбрасывается и обрабатывается в рамках одного блока приложения, то класс исключения следует объявлять в соответствующем модуле. Если же исключение выбрасывается на Middleware, а обрабатывается на клиентском уровне, то класс исключения необходимо объявлять в модуле global.

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

4.2.11.2. Передача исключений Middleware

Если при выполнении запроса от клиента на Middleware возникает исключение, выполнение прерывается и на клиента возвращается объект исключения, как правило, включающий цепочку порождающих друг друга исключений. Так как цепочка исключений может содержать классы, недоступные клиентскому блоку (например, исключения JDBC-драйвера), на клиента передается не сама эта цепочка, а ее представление внутри специального создаваемого исключения RemoteException.

Информация об исключениях-причинах сохраняется в виде списка объектов RemoteException.Cause. Каждый объект Cause хранит обязательно имя класса исключения и его сообщение. Кроме того, если класс исключения "поддерживается клиентом", то Cause содержит также и сам объект исключения. Это дает возможность передать на клиента информацию в полях исключения.

Класс исключения, объекты которого нужно передавать на клиентский уровень именно в виде Java-объектов, нужно аннотировать @SupportedByClient, например:

@SupportedByClient
public class WorkflowException extends RuntimeException {
...

Таким образом, при возникновении на Middleware исключения, не аннотированного @SupportedByClient, вызывающий клиентский код получит RemoteException, внутри которого будет находиться исходное исключение в виде строки. Если же исходное исключение аннотировано @SupportedByClient, то вызывающий код получит именно его. Это дает возможность в прикладном коде организовывать обработку декларируемых сервисами Middleware исключений традиционным образом - с помощью блоков try...catch.

Следует иметь в виду, что чтобы поддерживаемое клиентом исключение было действительно передано на клиента в виде объекта, оно не должно содержать внутри себя в цепочке getCause() неподдерживаемых исключений. Поэтому если вы создаете на Middleware экземпляр исключения и хотите передать его на клиента, указывайте для него параметр cause только если вы уверены, что он содержит только исключения, известные клиенту.

Упаковку объектов исключений в RemoteException перед передачей на клиентский уровень выполняет перехватчик вызовов сервисов - класс ServiceInterceptor. Кроме того, он же выполняет логгирование исключений. По умолчанию в журнал выводится вся информация об исключении, включая полный stack trace. Если это нежелательно, можно добавить классу исключения аннотацию @Logging, указав в ней тип логгирования:

  • FULL - (по умолчанию) полная информация, включая stacktrace

  • BRIEF - только имя класса исключения и сообщение

  • NONE - не выводить ничего

Например:

@SupportedByClient
@Logging(Logging.Type.BRIEF)
public class FinancialTransactionException extends Exception {
...

4.2.11.3. Обработчики исключений клиентского уровня

Необработанные исключения в блоках Web Client и Desktop Client, возникшие на клиентском уровне или переданные с Middleware, попадают в специальный механизм обработчиков. Этот механизм реализован в модуле GUI и доступен обоим клиентам.

Обработчик должен быть управляемым бином, реализовывать интерфейс GenericExceptionHandler, в методе handle() которого производить обработку и возвращать true, либо сразу возвращать false, если данный обработчик не может обработать переданное ему исключение. Такое поведение позволяет организовать "цепочку ответственности" обработчиков.

Рекомендуется наследовать классы своих обработчиков от базового класса AbstractGenericExceptionHandler, который умеет разбирать цепочку исключений (с учетом упакованных внутри RemoteException) и реагировать на конкретные типы исключений. Типы исключений, для которых предназначен данный обработчик, указываются в массиве строк, передаваемом в конструкторе обработчика базовому конструктору. Каждая строка массива должна содержать одно полное имя класса обрабатываемого исключения, например:

@ManagedBean("cuba_EntityAccessExceptionHandler")
public class EntityAccessExceptionHandler extends AbstractGenericExceptionHandler {

    public EntityAccessExceptionHandler() {
        super(EntityAccessException.class.getName());
    }
...

Если класс исключения недоступен на клиенте, следует указывать его имя строковым литералом:

@ManagedBean("cuba_OptimisticExceptionHandler")
public class OptimisticExceptionHandler extends AbstractGenericExceptionHandler implements Ordered {

    public OptimisticExceptionHandler() {
        super("org.springframework.orm.jpa.JpaOptimisticLockingFailureException");
    }
...

В случае использования в качестве базового класса AbstractGenericExceptionHandler логика обработки располагается в методе doHandle(), и может выглядеть следующим образом:

@Override
protected void doHandle(String className, String message, @Nullable Throwable throwable, WindowManager windowManager) {
    String msg = messages.getMainMessage("zeroBalance.message");
    windowManager.showNotification(msg, IFrame.NotificationType.ERROR);
}

Если имени класса исключения недостаточно для того, чтобы принять решение о применимости данного обработчика к исключению, следует определить метод canHandle(), получающий кроме прочего текст исключения. Метод должен вернуть true, если данный обработчик применим для исключения. Например:

@ManagedBean("cuba_NumericOverflowExceptionHandler")
public class NumericOverflowExceptionHandler extends AbstractGenericExceptionHandler {

    public NumericOverflowExceptionHandler() {
        super(ReportingSQLException.class.getName());
    }

    @Override
    protected boolean canHandle(String className, String message, @Nullable Throwable throwable) {
        return StringUtils.containsIgnoreCase(message, "Numeric field overflow");
    }
...

4.3. Компоненты работы с базой данных

В данном разделе приведена информация о возможных типах СУБД приложений на платформе CUBA. Кроме того, описан механизм на основе скриптов, с помощью которого можно создать новую базу данных, и в дальнейшем поддерживать ее в актуальном состоянии на протяжении всего цикла разработки и эксплуатации приложения.

Компоненты работы с базой данных принадлежат блоку Middleware, другие блоки приложения не имеют прямого доступа к БД.

Дополнительная практическая информация по работе с базой данных приведена в Раздел 5.5, «Проектирование БД» и Раздел 6.5, «Создание и обновление БД при эксплуатации приложения».

4.3.1. Типы СУБД

Тип используемой СУБД определяется свойствами приложения cuba.dbmsType и (опционально) cuba.dbmsVersion, а также настройкой источника данных javax.sql.DataSource, через который производится обращение к базе данных. Экземпляр источника данных извлекается из JNDI по имени, заданному в свойстве приложения cuba.dataSourceJndiName . Конфигурационный файл для Tomcat, определяющий источник данных, описан в Раздел A.1, «context.xml»

Платформа "из коробки" поддерживает следующие СУБД:

 cuba.dbmsTypecuba.dbmsVersion
HSQLDBhsql 
PostgreSQL 8.4+postgres 
Microsoft SQL Server 2005, 2008mssql 
Microsoft SQL Server 2012+mssql2012
Oracle Database 11goracle 

Таблица ниже описывает рекомендованное соответствие типов данных между атрибутами сущностей в Java и колонками таблиц различных СУБД. Эти типы автоматически выбираются Studio при генерации скриптов создания и обновления БД, и для них гарантируется работоспособность всех механизмов платформы.

JavaHSQLPostgreSQLMS SQL ServerOracle
UUIDvarchar(36)uuiduniqueidentifiervarchar2(32)
Datetimestamptimestampdatetimetimestamp
java.sql.Datetimestampdatedatetimedate
java.sql.Timetimestamptimedatetimetimestamp
BigDecimaldecimal(p, s)decimal(p, s)decimal(p, s)number(p, s)
Doubledouble precisiondouble precisiondouble precisionfloat
Longbigintbigintbigintnumber(19)
Integerintegerintegerintegerinteger
Booleanbooleanbooleantinyintchar(1)
String (limited)varchar(n)varchar(n)varchar(n)varchar2(n)
String (unlimited)longvarchartextvarchar(max)clob
byte[]longvarbinarybyteaimageblob

Как правило, всю работу по преобразованию данных между БД и кодом Java выполняет слой ORM совместно с соответствующим JDBC драйвером. Это означает, что при работе с данными через методы EntityManager и запросы на JPQL никакой ручной конвертации выполнять не нужно - вы просто используете типы Java, перечисленные в левой колонке таблицы.

При использовании native SQL через EntityManager.createNativeQuery() или через QueryRunner для разных типов СУБД некоторые типы данных в Java коде будут отличаться от приведенных. В первую очередь это касается атрибутов типа UUID - только драйвер PostgreSQL возвращает значения соответствующих колонок в этом типе, для других серверов это будет String. Для обеспечения независимости кода от используемой СУБД рекомендуется конвертировать типы параметров и результатов запросов с помощью интерфейса DbTypeConverter .

4.3.1.1. Поддержка произвольных СУБД

На уровне прикладного проекта можно реализовать работу с любой СУБД, поддерживаемой фреймворком ORM (OpenJPA). Для этого достаточно выполнить следующее:

  • Указать тип СУБД в виде произвольного кода в свойстве cuba.dbmsType. Код должен отличаться от используемых в платформе кодов hsql, postgres, mssql, oracle.

  • Реализовать интерфейсы DbmsFeatures, SequenceSupport, DbTypeConverter классами с именами соответственно TypeDbmsFeatures, TypeSequenceSupport, TypeDbTypeConverter, где Type - код типа СУБД. Пакет класса имплементации должен быть таким же, как у интерфейса.

  • Если проект включает базовый проект Workflow, необходимо переопределить бин CubaJbpmSpringHelper и его метод getHibernateDialectName() для выбора диалекта Hibernate, используемого в jBPM.

  • Создать скрипты инициализации и обновления БД в каталогах с кодом СУБД. Скрипты инициализации должны включать создание всех объектов БД, необходимых для сущностей платформы (их можно скопировать из имеющихся в каталоге 10-cuba и др. скриптов и исправить для данной СУБД).

  • Для создания и обновления БД задачами Gradle в build.gradle необходимо для этих задач указать дополнительные параметры:

    task createDb(dependsOn: assemble, type: CubaDbCreation) {
      dbms = 'my'                                            // DBMS code
      driver = 'net.my.jdbc.Driver'                          // JDBC driver class
      dbUrl = 'jdbc:my:myserver://192.168.47.45/mydb'        // Database URL
      masterUrl = 'jdbc:my:myserver://192.168.47.45/master'  // URL of a master DB to connect to for creating the application DB
      dropDbSql = 'drop database mydb;'                      // Drop database statement
      createDbSql = 'create database mydb;'                  // Create database statement
      timeStampType = 'datetime'                             // Date and time datatype - needed for SYS_DB_CHANGELOG table creation
      dbUser = 'sa'
      dbPassword = 'saPass1'
    }
    
    task updateDb(dependsOn: assemble, type: CubaDbUpdate) {
      dbms = 'my'                                            // DBMS code
      driver = 'net.my.jdbc.Driver'                          // JDBC driver class
      dbUrl = 'jdbc:my:myserver://192.168.47.45/mydb'        // Database URL
      dbUser = 'sa'
      dbPassword = 'saPass1'
    }

4.3.1.2. Версия СУБД

В дополнение к свойству приложения cuba.dbmsType существует опциональное свойство cuba.dbmsVersion. Оно влияет на выбор имплементаций интерфейсов DbmsFeatures, SequenceSupport, DbTypeConverter, и на поиск скриптов создания и обновления БД.

Имя класса имплементации интеграционного интерфейса формируется следующим образом: TypeVersionName. Здесь Type - значение cuba.dbmsType с заглавной буквы, Version - значение cuba.dbmsVersion, Name - имя интерфейса. Пакет класса должен быть таким же, как у интерфейса. Если класс с таким именем отсутствует, предпринимается попытка найти класс с именем без версии: TypeName. Если и такого класса нет, выдается исключение.

Например, в платформе определен класс com.haulmont.cuba.core.sys.persistence.Mssql2012SequenceSupport, который вступит в силу, если в проекте указаны следующие свойства:

cuba.dbmsType = mssql
cuba.dbmsVersion = 2012

При поиске скриптов создания и обновления БД каталог с именем type-version имеет приоритет над каталогом с именем type. Это значит, что скрипты каталога type-version заменяют одноименные скрипты каталога type. В каталоге type-version могут быть и скрипты с собственными именами, они будут также добавлены в общий набор скриптов для выполнения. Сортировка скриптов производится по пути начиная с каталога, вложенного в type или type-version, то есть без учета того, в каком каталоге (с версией или без) находится скрипт.

Например, следующим образом можно определить скрипты создания БД для Microsoft SQL Server для версий ниже и выше 2012:

modules/core/db/init/
   mssql/
       10.create-db.sql
       20.create-db.sql
       30.create-db.sql
   mssql-2012/
       10.create-db.sql 

4.3.2. Скрипты создания и обновления БД

Проект CUBA-приложения всегда содержит два набора скриптов:

  • Скрипты создания БД, предназначенные для создания базы данных с нуля. Они содержат набор DDL и DML операторов, после выполнении которых на пустой БД схема базы данных полностью соответствует текущему состоянию модели данных приложения. Скрипты создания могут также наполнять БД необходимыми первичными данными.

  • Скрипты обновления БД - предназначены для поэтапного приведения структуры БД к текущему состоянию модели данных.

При изменении модели данных необходимо отразить соответствующее изменение схемы БД и в скриптах содания, и в скриптах обновления. Например, при добавлении атрибута address в сущность Customer, нужно:

  1. Изменить оператор создания таблицы в скрипте создания:

    create table SALES_CUSTOMER (
      ID varchar(36) not null ,
      CREATE_TS timestamp,
      CREATED_BY varchar(50),
      --
      NAME varchar(100),
      ADDRESS varchar(200), -- added column
      --
      primary key (ID)
    )
  2. Добавить скрипт обновления, содержащий оператор модификации таблицы:

    alter table SALES_CUSTOMER add ADDRESS varchar(200)

Скрипты создания располагаются в каталоге /db/init модуля core. Для каждого типа СУБД, поддерживаемой приложением, создается свой набор скриптов и располагается в подкаталоге с именем, соответствующим свойству приложения cuba.dbmsType , например, /db/init/postgres. Имена скриптов создания должны иметь вид {optional_prefix}create-db.sql.

Скрипты обновления располагаются в каталоге /db/update модуля core. Для каждого типа СУБД, поддерживаемой приложением, создается свой набор скриптов и располагается в подкаталоге с именем, соответствующим свойству приложения cuba.dbmsType , например, /db/update/postgres.

Скрипты обновления могут быть двух типов: с расширением *.sql или с расширением *.groovy. SQL-скрипты являются основным средством обновления базы данных. Groovy-скрипты выполняются только механизмом запуска скриптов БД сервером, поэтому применяются в основном на этапе эксплуатации приложения - как правило, это процессы миграции или импорта данных, которые невозможно реализовать на SQL.

Скрипты обновления должны иметь имена, которые при сортировке в алфавитном порядке образуют правильную последовательность их выполнения (обычно это хронологическая последовательность их создания). Поэтому при ручном создании рекомендуется задавать имя скрипта обновления в виде {yymmdd}-{description}.sql, где yy - год, mm - месяц, dd - день, description - краткое описание скрипта. Например, 121003-addCodeToCategoryAttribute.sql. Studio при автоматической генерации скриптов также придерживается этого формата.

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

В развернутом приложении скрипты создания и обновления БД располагаются в специальном каталоге скриптов базы данных, задаваемым свойством приложения cuba.dbDir .

4.3.2.1. Структура SQL-скриптов

SQL-скрипты создания и обновления представляют собой текстовые файлы с набором DDL и DML команд, разделенных символом "^". Символ "^" применяется для того, чтобы можно было применять разделитель ";" в составе сложных команд, например, при создании функций или триггеров. Механизм исполнения скриптов разделяет входной файл на команды по разделителю "^" и выполняет каждую команду в отдельной транзакции. Это означает, что при необходимости можно сгруппировать несколько простых операторов (например, insert), разделенных точкой с запятой, и обеспечить их выполнение в одной транзакции.

Пример SQL-скрипта обновления:

create table LIBRARY_COUNTRY (
  ID varchar(36) not null,
  CREATE_TS time,
  CREATED_BY varchar(50),
  --
  NAME varchar(100) not null,
  --
  primary key (ID)
)^

alter table LIBRARY_TOWN add column COUNTRY_ID varchar(36) ^
alter table LIBRARY_TOWN add constraint FK_LIBRARY_TOWN_COUNTRY_ID foreign key (COUNTRY_ID) references LIBRARY_COUNTRY(ID)^
create index IDX_LIBRARY_TOWN_COUNTRY on LIBRARY_TOWN (COUNTRY_ID)^

4.3.2.2. Структура Groovy-скриптов

Groovy-скрипты обновления имеют следующую структуру:

  • Основная часть, содержащая код, выполняемый до старта контекста приложения. В этой части можно использовать любые классы Java, Groovy и блока Middleware приложения, но при этом необходимо иметь в виду, что никакие бины, интерфейсы инфраструктуры и прочие объекты приложения еще не инстанциированы, и с ними работать нельзя.

    Основная часть предназначена в первую очередь, как и обычные SQL-скрипты, для обновления схемы данных.

  • PostUpdate часть - набор замыканий, которые будут выполнены после завершения процесса обновления и после старта контекста приложения. Внутри этих замыканий можно оперировать любыми объектами Middleware приложения.

    В этой части скрипта удобно, напимер, выполнять импорт данных, так как в ней можно использовать интерфейс Persistence и объекты модели данных.

На вход Groovy-скриптов механизм выполнения передает следующие переменные:

  • ds - экземпляр javax.sql.DataSource для базы данных приложения.

  • log - экземпляр org.apache.commons.logging.Log для вывода сообщений в журнал сервера

  • postUpdate - объект, содержащий метод add(Closure closure) для добавления замыканий, выполняющихся после старта контекста сервера.

Groovy-скрипты выполняются только механизмом запуска скриптов БД сервером.

Пример Groovy-скрипта обновления:

import com.haulmont.cuba.core.Persistence
import com.haulmont.cuba.core.global.AppBeans
import com.haulmont.refapp.core.entity.Colour
import groovy.sql.Sql

log.info('Executing actions in update phase')

Sql sql = new Sql(ds)
sql.execute """
alter table MY_COLOR add DESCRIPTION varchar(100);
"""

// Add post update action
postUpdate.add({
  log.info('Executing post update action using fully functioning server')

  def p = AppBeans.get(Persistence.class)
  def tr = p.createTransaction()
  try {
      def em = p.getEntityManager()

      Colour c = new Color()
      c.name = 'yellow'
      c.description = 'a description'

      em.persist(c)
      tr.commit()
  } finally {
      tr.end()
  }
})

4.3.3. Выполнение скриптов БД задачами Gradle

Данный механизм применяется обычно разработчиками приложения для собственного экземпляра базы данных. Выполнение скриптов в этом случае сводится к запуску специальных задач Gradle, описанных в скрипте сборки build.gradle . Это можно сделать как из командной строки, так и с помощью интерфейса Studio.

Для запуска скриптов создания БД служит задача createDb. В Studio ей соответствует команда главного меню Run -> Create database. При запуске задачи происходит следующее:

  1. В каталоге modules/core/build/db собираются скрипты базовых проектов платформы и скрипты db/**/*.sql модуля core текущего проекта. Наборы скриптов базовых проектов располагаются в подкаталогах с числовыми префиксами начиная с 10, скрипты текущего проекта - в подкаталоге с префиксом 50. Числовые префиксы необходимы для соблюдения алфавитного порядка выполнения скриптов - сначала выполняются скрипты cuba, затем других базовых проектов, затем текущего проекта.

  2. Если БД существует, она полностью очищается. Если не существует, то создается новая пустая БД.

  3. Последовательно в алфавитном порядке выполняются все скрипты создания modules/core/build/db/init/**/*create-db.sql, и их имена вместе с путем относительно каталога db регистрируются в таблице SYS_DB_CHANGELOG.

  4. В таблице SYS_DB_CHANGELOG аналогично регистрируются все имеющиеся на данный момент скрипты обновления modules/core/build/db/update/**/*.sql. Это необходимо для будущего инкрементального обновления БД новыми скриптами.

Для запуска скриптов обновления БД служит задача updateDb. В Studio ей соответствует команда главного меню Run -> Update database. При запуске задачи происходит следующее:

  1. Производится сборка скриптов аналогично описанному выше.

  2. Производится проверка, все ли базовые проекты имеют необходимые таблицы в базе данных. Если обнаруживается, что БД не инициализирована для работы некоторого базового проекта, выполняются его скрипты создания.

  3. В каталогах modules/core/build/db/update/** производится поиск скриптов обновления, не зарегистрированных в таблице SYS_DB_CHANGELOG, то есть не выполненных ранее и содержимое которых не отражено в БД при ее инициализации.

  4. Последовательно в алфавитном порядке выполняются все найденные на предыдущем шаге скрипты, и их имена вместе с путем относительно каталога db регистрируются в таблице SYS_DB_CHANGELOG.

4.3.4. Выполнение скриптов БД сервером

Механизм выполнения скриптов сервером предназначен для приведения БД в актуальное состояние на старте сервера приложения, и активируется во время инициализации блока Middleware. Понятно, что при этом приложение должно быть собрано и развернуто на сервере, будь то собственный Tomcat разработчика или сервер в режиме эксплуатации.

Данный механизм в зависимости от описанных ниже условий выполняет либо скрипты создания, либо скрипты обновления, то есть он может и инициализировать БД с нуля, и обновлять ее. Однако, в отличие от описанной в предыдущем разделе задачи Gradle createDb, для выполнения инициализации базы она должна существовать - сервер не создает БД автоматически, а только прогоняет на ней скрипты.

Механизм выполнения скриптов сервером действует следующим образом:

  • Скрипты извлекаются из каталога скриптов базы данных, определяемого свойством приложения cuba.dbDir . В стандартном варианте развертывания в Tomcat это tomcat/webapps/app-core/WEB-INF/db.

  • Если в БД отсутствует таблица SEC_USER, то считается, что база данных пуста, и запускается полная инициализация с помощью скриптов создания БД. После выполнения инициализирующих скриптов их имена запоминаются в таблице SYS_DB_CHANGELOG. Кроме того, там же сохраняются имена всех доступных скриптов обновления, без их выполнения.

  • Если в БД имеется таблица SEC_USER, но отсутствует таблица SYS_DB_CHANGELOG (это случай, когда в первый раз запускается описываемый механизм на имеющейся рабочей БД), никакие скрипты не запускаются. Вместо этого создается таблица SYS_DB_CHANGELOG и в ней сохраняются имена всех доступных на данный момент скриптов создания и обновления.

  • Если в БД имеются и таблица SEC_USER и таблица SYS_DB_CHANGELOG, то производится запуск скриптов обновления, и их имена запоминаются в таблице SYS_DB_CHANGELOG. Причем запускаются только те скрипты, имен которых до этого не было в таблице SYS_DB_CHANGELOG, т.е. не запускавшиеся ранее. Последовательность запуска скриптов определяется 2-мя факторами: приоритетом базового проекта (см. содержимое каталога скриптов базы данных: 10-cuba, 20-workflow, ...) и именем файла скрипта (с учетом подкаталогов внутри каталога update) в алфавитном порядке.

    Перед выполнением скриптов обновления производится проверка, все ли базовые проекты имеют необходимые таблицы в базе данных. Если обнаруживается, что БД не инициализирована для работы некоторого базового проекта, выполняются его скрипты создания.

Механизм выполнения скриптов на старте сервера включается свойством приложения cuba.automaticDatabaseUpdate .

В запущенном приложении механизм выполнения скриптов можно стартовать с помощью JMX-бина app-core.cuba:type=PersistenceManager, вызвав его метод updateDatabase() с параметром update. Понятно, что таким способом можно только обновить БД, а не проинициализировать новую, так как войти в систему для запуска метода JMX-бина при пустой БД невозможно. При этом следует иметь в виду, что если на старте Middleware или при входе пользователя в систему начнется инициализация той части модели данных, которая уже не соответствует устаревшей схеме БД, то произойдет ошибка, и продолжение работы станет невозможным. Именно поэтому универсальным является только автоматическое обновление БД на старте сервера перед инициализацией модели данных.

JMX-бин app-core.cuba:type=PersistenceManager имеет еще один метод, относящийся к механизму обновления БД: findUpdateDatabaseScripts(). Он возвращает список новых скриптов обновления, имеющихся в каталоге и не зарегистрированных в БД.

Практические рекомендации по использованию механизма обновления БД сервером приведены в Раздел 6.5, «Создание и обновление БД при эксплуатации приложения».

4.4. Компоненты среднего слоя

На следующем рисунке приведены основные компоненты среднего слоя CUBA-приложения.

Рисунок 13. Компоненты среднего слоя

Компоненты среднего слоя

Services – управляемые контейнером компоненты, формирующие границу приложения и предоставляющие интерфейс клиентскому уровню приложения. Сервисы могут содержать бизнес-логику сами, либо делегировать выполнение Managed Beans.

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

Persistence − инфраструктурный интерфейс для доступа к функциональности хранения данных: управлению транзакциями и ORM.

4.4.1. Сервисы

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

Основные задачи сервисов:

  • Предоставляют удаленный (remote) интерфейс для вызова с клиентского уровня

  • Проверяют наличие активной пользовательской сессии, соответствующей идентификатору сессии, переданному с клиента

  • Записывают в журнал необработанные исключения среднего слоя

Кроме того, именно в слое сервисов рекомендуется выполнять авторизацию текущего пользователя, т.е. проверять его права на ту или иную функциональность.

Общие для всех сервисов задачи решаются следующим образом:

  • Проверка наличия пользовательской сессии и логгирование исключений производится классом-интерцептором ServiceInterceptor, который перехватывает выполнение каждого метода сервиса с помощью Spring AOP

  • Удаленный интерфейс для доступа к сервису через Spring HTTP Invoker создается бином RemoteServicesBeanCreator, который конфигурируется в файле remoting-spring.xml модуля core.

Рисунок 14. Диаграмма классов сервиса

Диаграмма классов сервиса

4.4.1.1. Создание сервиса

Имена интерфейсов сервисов должны заканчиваться на Service, имена классов реализации на ServiceBean.

При создании сервиса необходимо выполнить следующее:

  1. Создать интерфейс в модуле global (т.к. интерфейс сервиса должен быть доступен на всех уровнях) и задать в нем имя сервиса. Имя рекомендуется задавать в формате {имя_проекта}_{имя_интерфейса}. Например:

    package com.sample.sales.core;
    
    import com.sample.sales.entity.Order;
    
    public interface OrderService {
        String NAME = "sales_OrderService";
    
        void calculateTotals(Order order);
    }
  2. Создать класс сервиса в модуле core и добавить ему аннотацию @org.springframework.stereotype.Service с именем, заданным в интерфейсе

    package com.sample.sales.core;
    
    import com.sample.sales.entity.Order;
    import org.springframework.stereotype.Service;
    
    @Service(OrderService.NAME)
    public class OrderServiceBean implements OrderService {
        @Override
        public void calculateTotals(Order order) {
        }
    }

    Класс сервиса, как и класс любого другого управляемого бина, должен находиться внутри дерева пакетов с корнем, заданным в элементе context:component-scan файла spring.xml . В нашем случае файл spring.xml содержит элемент:

    <context:component-scan base-package="com.sample.sales"/>

    что означает, что поиск аннотированных бинов для данного блока приложения будет происходить начиная с пакета com.sample.sales.

Сервисы предназначены только для вызова "снаружи" Middleware. Не рекомендуется вызывать методы сервисов из других компонентов среднего слоя. При обнаружении факта вызова сервиса из другого сервиса в журнал выводится сообщение об ошибке.

Если некоторую бизнес-логику требуется вызывать из разных сервисов либо других компонентов Middleware, ее необходимо выделить и инкапсулировать внутри соответствующего Managed Bean.

4.4.1.2. Использование сервиса

Для того чтобы вызывать сервис, в клиентском блоке приложения для него должен быть создан соответствующий прокси-объект. Делается это путем объявления имени и интерфейса сервиса в параметрах фабрики прокси-объектов. Для блока Web Client это бин класса WebRemoteProxyBeanCreator, для Web Portal - PortalRemoteProxyBeanCreator , для Desktop Client - RemoteProxyBeanCreator .

Фабрика прокси-объектов конфигурируется в файле spring.xml соответствующего клиентского блока.

Например, чтобы в приложении sales вызвать с веб-клиента сервис sales_OrderService, необходимо добавить в файл web-spring.xml модуля web следующее:

<bean id="sales_proxyCreator" class="com.haulmont.cuba.web.sys.remoting.WebRemoteProxyBeanCreator">
    <property name="clusterInvocationSupport" ref="cuba_clusterInvocationSupport"/>
    <property name="remoteServices">
        <map>
            <entry key="sales_OrderService" value="com.sample.sales.core.OrderService"/>
        </map>
    </property>
</bean>

Все импортируемые сервисы объявляются в одном свойстве remoteServices в элементах map/entry.

С точки зрения прикладного кода прокси-объект сервиса на клиентском уровне является обычным бином Spring и может быть получен либо инжекцией, либо с помощью класса AppBeans, например:

@Inject
protected OrderService orderService;
...
orderService.calculateTotals(order);

4.4.1.3. DataService

DataService является фасадом для вызова серверной релизации DataManager с клиентского уровня. DataService не рекомендуется использовать в прикладном коде. Вместо него и на клиентском уровне, и на Middleware следует использовать DataManager.

4.4.2. Системная аутентификация

При выполнении пользовательских запросов программному коду Middleware через интерфейс UserSessionSource всегда доступна информация о текущем пользователе. Это возможно потому, что при получении запроса с клиентского уровня в потоке выполнения автоматически устанавливается соответствующий объект SecurityContext .

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

Такого рода аутентификация называется системной, так как не требует участия пользователя - средний слой приложения просто создает (или использует имеющуюся) пользовательскую сессию, и устанавливает в потоке выполнения соответствующий объект SecurityContext.

Обеспечить системную аутентификацию некоторого участка кода можно следующими способами:

  • явно используя бин com.haulmont.cuba.security.app.Authentication, например:

    @Inject
    protected Authentication authentication;
    ...
    authentication.begin();
    try {
        // authenticated code
    } finally {
        authentication.end();
    }
  • добавив методу бина аннотацию @Authenticated, например:

    @Authenticated
    public String foo(String value) {
        // authenticated code
    }

Во втором случае также используется бин Authentication, но неявно, через интерцептор AuthenticationInterceptor, который перехватывает вызовы всех методов бинов с аннотацией @Authenticated.

В приведенных примерах пользовательская сессия будет создаваться от лица пользователя, логин которого указан в свойстве приложения cuba.jmxUserLogin . Если требуется аутентификация от имени другого пользователя, нужно воспользоваться первым вариантом и передать в метод begin() логин нужного пользователя.

Если в момент выполнения Authentication.begin() в текущем потоке выполнения присутствует активная пользовательская сессия, то она не заменяется - соответственно, код, требующий аутентификации, будет выполняться с имеющейся сессией, и последующий метод end() не будет очищать поток.

Например, вызов метода JMX-бина из встроенной в Web Client консоли JMX, если бин находится в той же JVM, что и блок WebClient, к которому в данный момент подключен пользователь, будет выполнен от имени текущего зарегистрированного в системе пользователя, независимо от наличия системной аутентификации.

4.4.3. Интерфейс Persistence

Интерфейс инфраструктуры, являющийся точкой входа в функциональность хранения данных в БД.

Методы интерфейса:

  • createTransaction(), getTransaction() - получить интерфейс управления транзакциями

  • isInTransaction() - определяет, существует ли в данный момент активная транзакция

  • getEntityManager() - возвращает экземпляр EntityManager для текущей транзакции

  • isSoftDeletion() - позволяет определить, активен ли режим мягкого удаления

  • setSoftDeletion() - устанавливает или отключает режим мягкого удаления. Влияет на аналогичный признак всех создаваемых экземпляров EntityManager. По умолчанию мягкое удаление включено.

  • getDbTypeConverter() - возвращает экземпляр DbTypeConverter для используемой в данный момент базы данных.

  • getDataSource() - получить javax.sql.DataSource для используемой в данный момент базы данных.

    Для всех объектов javax.sql.Connection, получаемых методом getDataSource().getConnection(), необходимо после использования соединения вызвать метод close() в секции finally. В противном случае соединение не вернется в пул, через какое-то время пул переполнится, и приложение не сможет выполнять запросы к базе данных.

  • getTools() - возвращает экземпляр интерфейса PersistenceTools (см. ниже).

4.4.3.1. PersistenceTools

ManagedBean, содержащий вспомогательные методы работы с хранилищем данных. Интерфейс PersistenceTools можно получить либо методом Persistence.getTools(), либо как любой другой бин - инжекцией или через класс AppBeans.

Методы PersistenceTools:

  • getDirtyFields() - возвращает коллекцию имен атрибутов сущности, измененных со времени последней загрузки экземпляра из БД. Для новых экземпляров возвращает пустую коллекцию.

  • isLoaded() - определяет, загружен ли из БД указанный атрибут экземпляра. Атрибут может быть не загружен, если он не указан в примененном при загрузке представлении.

    Данный метод работает только для экземпляров в состоянии Managed.

  • getReferenceId() - возвращает идентификатор связанной сущности без загрузки ее из БД.

    Предположим, в персистентный контекст загружен экземпляр Order, и нужно получить значение идентификатора экземпляра Customer, связанного с данным Заказом. Стандартное решение order.getCustomer().getId() приведет к выполнению SQL запроса к БД для загрузки экземпляра Customer, что в данном случае избыточно, так как значение идентификатора Покупателя физически находится также и в таблице Заказов. Выполнение же

    persistence.getTools().getReferenceId(order, "customer")

    не вызовет никаких дополнительных запросов к базе данных.

    Данный метод работает только для экземпляров в состоянии Managed.

Для расширения набора вспомогательных методов в конкретном приложении бин PersistenceTools можно переопределить. Примеры работы с расширенным интерфейсом:

MyPersistenceTools tools = persistence.getTools();
tools.foo();
((MyPersistenceTools) persistence.getTools()).foo();

4.4.3.2. PersistenceHelper

Вспомогательный класс для получения информации о персистентных сущностях. В отличие от бинов Persistence и PersistenceTools доступен на всех уровнях приложения.

Методы PersistenceHelper:

  • isNew() - определяет, является ли переданный экземпляр только что созданным, т.е. находящимся в состоянии New. Возвращает true, также если экземпляр не является персистентной сущностью.

  • isDetached() - определяет, находится ли переданный экземпляр в состоянии Detached. Возвращает true, также если экземпляр не является персистентной сущностью.

  • isSoftDeleted() - определяет, поддерживает ли переданный класс сущности мягкое удаление

  • getEntityName() - возвращает имя сущности, заданное в аннотации @Entity

  • getTableName() - возвращает имя таблицы БД, хранящей экземпляры сущности, заданное в аннотации @Table

4.4.3.3. DbTypeConverter

Интерфейс, определяющий методы для конвертации данных между значениями атрибутов модели данных и параметрами и результатами запросов JDBC. Объект данного интерфейса можно получить методом Persistence.getDbTypeConverter().

Методы DbTypeConverter:

  • getJavaObject() - конвертирует результат JDBC запроса в тип, подходящий для присвоения атрибуту сущности.

  • getSqlObject() - конвертирует значение атрибута сущности в тип, подходящий для присвоения параметру JDBC запроса.

  • getSqlType() - возвращает константу из java.sql.Types, соответствующую переданному типу атрибута сущности.

4.4.4. Слой ORM

Object-Relational Mapping - объектно-реляционное отображение - технология связывания таблиц реляционной базы данных с объектами языка программирования.

Преимущества использования ORM:
  • Позволяет работать с данными реляционной СУБД, манипулируя объектами Java

  • Упрощает программирование, избавляя от рутины написания тривиальных SQL-запросов

  • Упрощает программирование, позволяя извлекать и сохранять целые графы объектов одной командой

  • Обеспечивает легкое портирование приложения на различные СУБД

  • Использует лаконичный язык запросов JPQL

  • Оптимизирует количество выполняемых SQL-запросов на команды insert и update

Недостатки:
  • Требует понимания особенностей работы с ORM

  • Не позволяет напрямую оптимизировать SQL или использовать особенности применяемой СУБД

В платформе CUBA используется реализация ORM по стандарту Java Persistence API на основе фреймворка Apache OpenJPA.

4.4.4.1. EntityManager

EntityManager - основной интерфейс ORM, служит для управления персистентными сущностями.

Ссылку на EntityManager можно получить через интерфейс Persistence, вызовом метода getEntityManager(). Полученный экземпляр EntityManager привязан к текущей транзакции, то есть все вызовы getEntityManager() в рамках одной транзакции возвращают один и тот же экземпляр EntityManager. После завершения транзакции обращения к данному экземпляру невозможны.

Экземпляр EntityManager содержит в себе "персистентный контекст" – набор экземпляров сущностей, загруженных из БД или только что созданных. Персистентный контекст является своего рода кэшем данных в рамках транзакции. EntityManager автоматически сбрасывает в БД все изменения, сделанные в его персистентном контексте, в момент коммита транзакции, либо при явном вызове метода flush().

Интерфейс EntityManager, используемый в CUBA-приложениях, в основном повторяет стандартный javax.persistence.EntityManager. Рассмотрим его основные методы:

  • persist() - вводит новый экземпляр сущности в персистентный контекст. При коммите транзакции командой SQL INSERT в БД будет создана соответствующая запись.

  • merge() - переносит состояние отсоединенного экземпляра сущности в персистентный контекст следующим образом: из БД загружается экземпляр с тем же идентификатором, в него переносится состояние переданного Detached экземпляра и возвращается загруженный Managed экземпляр. Далее надо работать именно с возвращенным Managed экземпляром. При коммите транзакции командой SQL UPDATE в БД будет сохранено состояние данного экземпляра.

  • remove() - удалить объект из базы данных, либо, если включен режим мягкого удаления, установить атрибуты deleteTs и deletedBy.

    Если переданный экземпляр находится в Detached состоянии, сначала выполняется merge().

  • find() - загружает экземпляр сущности по идентификатору.

    При формировании запроса к БД учитывается представление, переданное в параметре данного метода, либо установленное для всего EntityManager методом setView(). В результате в персистентном контексте окажется граф объектов, для которого загружены все не-lazy атрибуты представления. Остальные атрибуты можно дозагрузить обращением к соответствующим методам доступа объектов, либо вызовом метода fetch().

  • createQuery() - создать объект Query для выполнения JPQL запроса.

    Рекомендуется использовать вариант метода с передачей класса сущности для получения экземпляра TypedQuery.

  • createNativeQuery() - создать объект Query для выполнения SQL запроса.

  • setView() - устанавливает представление по умолчанию, с которым будет производиться последующая загрузка сущностей методом find() либо JPQL запросами. В результате жадно загружены будут все не-lazy атрибуты представления.

    Если в данный метод передать null, либо не вызывать его вообще, загрузка будет производиться в соответствие с правилами аннотаций сущностей.

    Представления, явно переданные в метод find() или установленные в объекте Query имеют приоритет над установленным данным методом.

  • addView() - аналогичен методу setView(), но в случае наличия уже установленного в EntityManager представления, не заменяет его, а добавляет атрибуты переданного представления.

  • fetch() - обеспечивает для экземпляра сущности загрузку всех атрибутов указанного представления, включая lazy атрибуты. Экземпляр сущности должен быть в Managed состоянии.

    Данный метод рекомендуется вызывать перед коммитом транзакции, если представление содержит lazy атрибуты, а экземпляр сущности нужно отправить на клиентский уровень. В этом случае только после вызова fetch() можно быть уверенным, что все нужные клиентсткому коду атрибуты действительно загружены.

  • reload() - перезагрузить экземпляр сущности с указанным представлением. Обеспечивает загрузку всех атрибутов представления, вызывая внутри себя метод fetch().

  • isSoftDeletion() - проверяет, находится ли данный EntityManager в режиме мягкого удаления.

  • setSoftDeletion() - устанавливает режим мягкого удаления для данного экземпляра EntityManager.

  • getConnection() - возвращает java.sql.Connection, через который выполняет запросы данный экземпляр EntityManager, и, соответственно, текущая транзакция. Закрывать такое соединение не нужно, оно будет закрыто при завершении транзакции.

  • getDelegate() - возвращает javax.persistence.EntityManager, предоставляемый реализацией ORM.

4.4.4.2. Состояния сущности

New

Только что созданный в памяти экземпляр, например: Car car = new Car()

Новый экземпляр может быть передан в EntityManager.persist() для сохранения в БД, при этом он переходит в состояние Managed.

Managed

Загруженный из БД или новый, переданный в EntityManager.persist(), экземпляр. Принадлежит некоторому экземпляру EntityManager, другими словами, находится в его персистентном контексте.

Любые изменения экземпляра в состоянии Managed будут сохранены в БД в случае коммита транзакции, к которой принадлежит данный EntityManager

Detached

Экземпляр, загруженный из БД и отсоединенный от своего персистентного контекста (вследствие закрытия транзакции или сериализации).

Изменения, вносимые в Detached экземпляр, запоминаются в самом этом экземпляре (в полях, добавленных с помощью bytecode enhancement). Эти изменения будут сохранены в БД, только если данный экземпляр будет снова переведен в состояние Managed путем передачи в метод EntityManager.merge().

4.4.4.3. Загрузка по требованию

Загрузка по требованию (lazy loading) позволяет загружать связанные сущности отложенно, т.е. только в момент первого обращения к их свойствам.

Загрузка по требованию в сумме порождает больше запросов к БД, чем жадная загрузка (eager fetching), однако нагрузка при этом растянута во времени.

  • Например, при извлечении списка N экземпляров сущности A, содержащих ссылку на экземпляр сущности B, в случае загрузки по требованию будет выполнено N+1 запросов к базе данных.

  • Для минимизации времени отклика и снижения нагрузки необходимо стремиться к меньшему количеству обращений к БД. Для этого в платформе используется механизм представлений, с помощью которого в вышеописанном случае ORM может сформировать один запрос к БД с объединением таблиц.

  • Если A содержит коллекцию B, в случае жадной загрузки ORM сформирует SQL запрос, возвращающий произведение строк A и B.

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

Загрузка по требованию работает только для экземпляра в состоянии Managed, то есть внутри транзакции, загрузившей данный экземпляр.

4.4.4.4. Выполнение JPQL запросов

Для выполнения JPQL запросов предназначен интерфейс Query, ссылку на который можно получить у текущего экземпляра EntityManager вызовом метода createQuery(). Если запрос предполагается использовать для извлечения сущностей, рекомендуется вызывать createQuery() с передачей типа результата, что приведет к созданию TypedQuery.

Методы Query в основном соответствуют методам стандартного интерфейса javax.persistence.Query . Рассмотрим отличия.

  • setParameter() - устанавливает значение параметра запроса. При передаче в данный метод экземпляра сущности выполняет неявное преобразование экземпляра в его идентификатор. Например:

    Customer customer = ...;
    TypedQuery<Order> query = entityManager.createQuery(
        "select o from sales$Order o where o.customer.id = ?1", Order.class);
    query.setParameter(1, customer);

    Обратите внимание на сравнение в запросе по идентификатору, но передачу в качестве параметра самого экземпляра сущности.

    Вариант метода с передачей implicitConversions = false не выполняет такого преобразования.

  • setView(), addView() - аналогичны одноименным методам интерфейса EntityManager - устанавливают представление, используемое при загрузке данных текущим запросом, не влияя на представление всего EntityManager.

  • getDelegate() - возвращает экземпляр javax.persistence.Query, предоставляемый реализацией ORM.

При выполнении запроса через Query изменения в текущем персистентном контексте не учитываются, т.е. запрос просто выполняется в БД. Если результатом выборки являются экземпляры, уже находящиеся в персистентном контексте, то в результате запроса окажутся именно они, а не прочитанные из БД. Ситуацию поясняет следующий фрагмент теста:

TypedQuery<User> query;
List<User> list;

query = em.createQuery("select u from sec$User u where u.name = ?1", User.class);
query.setParameter(1, "testUser");
list = query.getResultList();
assertEquals(1, list.size());
User user = list.get(0);

user.setName("newName");

query = em.createQuery("select u from sec$User u where u.name = ?1", User.class);
query.setParameter(1, "testUser");
list = query.getResultList();
assertEquals(1, list.size());
User user1 = list.get(0);

assertTrue(user1 == user);

Такое поведение определяется параметром openjpa.IgnoreChanges=true, заданным в файле persistence.xml базового проекта cuba. В прикладном проекте данный параметр можно изменить, указав его в собственном persistence.xml.

Запросы, модифицирующие данные (update, delete) приводят к сбросу (flush) в базу данных текущего персистентного контекста перед выполнением. Другими словами, ORM сначала синхронизирует состояние сущностей в персистентном контексте и в БД, а уже потом выполняет модифицирующий запрос. Рекомендуется выполнять такие запросы в неизмененном персистентном контексте, чтобы исключить неявные действия ORM, которые могут отрицательно сказаться на производительности.

4.4.4.4.1. Поиск подстроки без учета регистра

Для удобного формирования условия поиска без учета регистра символов и по любой части строки можно использовать префикс (?i) в значении параметра запроса. Например, имеется запрос:

select c from sales$Customer c where c.name like :name

Если в значении параметра name передать строку (?i)%doe%, то при наличии в БД записи со значением John Doe она будет найдена, несмотря на раличие в регистре символа. Это произойдет потому, что ORM выполнит SQL с условием вида lower(C.NAME) like ?.

Следует иметь в виду, что при таком поиске индекс, созданный в БД по полю NAME, не используется.

4.4.4.4.2. Макросы в JPQL

Текст JPQL запроса может включать макросы, которые обрабатываются перед выполнением и превращаются в исполняемый JPQL, дополнительно модифицируя набор параметров.

Макросы, определенные в платформе, решают следующие задачи:

  • Позволяют обойти принципиальную невозможность средствами JPQL выразить условие зависимости значения поля от текущего момента времени (не работает арифметика типа current_date-1)

  • Позволяют сравнивать с датой поля типа Timestamp (содержащие дату+время)

Рассмотрим их подробно:

@between

Имеет вид @between(field_name, moment1, moment2, time_unit), где

  • field_name - имя атрибута для сравнения

  • moment1, moment2 - моменты времени, в которые должно попасть значение атрибута field_name. Каждый из моментов должен быть определен выражением с участием переменной now, к которой может быть прибавлено или отнято целое число

  • time_unit - определяет единицу измерения времени, которое прибавляется или вычитается из now в выражениях моментов, а также точность округления моментов. Может быть следующим: year, month, day, hour, minute, second. При включенном базовом проекте workflow можно также использовать единицы рабочего времени: workday, workhour, workminute.

Макрос преобразуется в следующее выражение JPQL: field_name >= :moment1 and field_name < :moment2

Пример 1. Покупатель создан сегодня:

select c from sales$Customer where @between(c.createTs, now, now+1, day)

Пример 2. Покупатель создан в течение последних 10 минут:

select c from sales$Customer where @between(c.createTs, now-10, now, minute)

Пример 3. Документы, датированные последними 5 рабочими днями (для проектов, включающих workflow):

select d from sales$Doc where @between(d.createTs, now-5, now, workday)
@today

Имеет вид @today(field_name) и обеспечивает формирование условия попадания значения атрибута в текущий день. По сути это частный случай макроса @between.

Пример. Пользователь создан сегодня:

select d from sales$Doc where @today(d.createTs)
@dateEquals

Имеет вид @dateEquals(field_name, parameter) и позволяет сформировать условие попадания значения поля field_name типа Timestamp в дату, задаваемую параметром parameter.

Пример:

select d from sales$Doc where @dateEquals(d.createTs, :param)
@dateBefore

Имеет вид @dateBefore(field_name, parameter) и позволяет сформировать условие, что дата значения поля field_name типа Timestamp меньше даты, задаваемой параметром parameter.

Пример:

select d from sales$Doc where @dateBefore(d.createTs, :param)
@dateAfter

Имеет вид @dateAfter(field_name, parameter) и позволяет сформировать условие, что дата значения поля field_name типа Timestamp больше или равна дате, задаваемой параметром parameter.

Пример:

select d from sales$Doc where @dateAfter(d.createTs, :param)
@enum

Позволяет использовать полное имя константы enum вместо ее идентификатора в БД. Это упрощает поиск использований enum в коде приложения.

Пример:

select r from sec$Role where r.type = @enum(com.haulmont.cuba.security.entity.RoleType.SUPER) order by r.name

Список макросов может быть расширен в прикладном проекте. Для создания нового макроса необходимо определить бин, реализующий интерфейс QueryMacroHandler, и задать ему @Scope("prototype"). Механизм выполнения JPQL запросов создает все доступные бины типа QueryMacroHandler, и по очереди передает им текст запроса с набором параметров. Очередность вызова обработчиков не определена.

4.4.4.5. Выполнение SQL запросов

ORM позволяет выполнять SQL запросы к базе данных, возвращая как списки отдельных полей, так и экземпляры сущностей. Для этого необходимо создать объект Query или TypedQuery вызовом одного из методов EntityManager.createNativeQuery().

Если выполняется выборка отдельных колонок таблицы, то результирующий список будет содержать строки в виде Object[]. Например:

Query query = em.createNativeQuery("select ID, NAME from SALES_CUSTOMER where NAME like ?1");
query.setParameter(1, "%Company%");
List list = query.getResultList();
for (Iterator it = list.iterator(); it.hasNext(); ) {
    Object[] row = (Object[]) it.next();
    UUID id = (UUID) row[0];
    String name = (String) row[1];
}

Следует иметь в виду, при использовании SQL колонки, соответствующие атрибутам сущностей типа UUID, возвращаются в виде UUID или в виде String, в зависимости от используемой СУБД и JDBC драйвера:

  • HSQLDB - String

  • PostgreSQL, драйвер postgresql-8.3-603.jdbc4.jar - String

  • PostgreSQL, драйвер postgresql-9.1-901.jdbc4.jar - UUID

  • Microsoft SQL Server, драйвер jtds-1.2.4.jar - String

  • Oracle - String

Параметры этого типа также должны задаваться либо как UUID, либо своим строковым представлением, в зависимости от используемой СУБД и JDBC драйвера. Для обеспечения независимости кода от используемой СУБД рекомендуется использовать DbTypeConverter .

Если вместе с текстом запроса передан класс результирующей сущности, то возвращается TypedQuery и после выполнения производится попытка отображения результатов запроса на атрибуты сущности. Например:

TypedQuery<Customer> query = em.createNativeQuery(
    "select * from SALES_CUSTOMER where NAME like ?1",
    Customer.class);
query.setParameter(1, "%Company%");
List<Customer> list = query.getResultList();

Поведение SQL запросов, возвращающих сущности, и модифицирующих запросов (update, delete), по отношению к текущему персистентному контексту аналогично описанному для JPQL запросов.

См. также Раздел 4.7.10, «Выполнение SQL с помощью QueryRunner».

4.4.4.6. Entity Listeners

Entity Listeners предназначены для реакции на события жизненного цикла экземпляров сущностей на уровне Middleware.

Слушатель представляет собой класс, реализующий один или несколько интерфейсов пакета com.haulmont.cuba.core.listener. Слушатель будет реагировать на события типов, соответствующих реализуемым интерфейсам.

BeforeDetachEntityListener

Метод onBeforeDetach() вызывается перед отделением объекта от EntityManager при коммите транзакции.

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

BeforeAttachEntityListener

Метод onBeforeAttach() вызывается перед введением объекта в персистентный контекст при выполнении операции EntityManager.merge().

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

BeforeInsertEntityListener

Метод onBeforeInsert() вызывается перед выполнением вставки записи в БД. В данном методе возможны любые операции с текущим EntityManager.

AfterInsertEntityListener

Метод onAfterInsert() вызывается после выполнения вставки записи в БД, но до коммита транзакции. В данном методе нельзя модифицировать текущий персистентный контекст, однако можно производить изменения в БД с помощью QueryRunner.

BeforeUpdateEntityListener

Метод onBeforeUpdate() вызывается перед изменением записи в БД. В данном методе возможны любые операции с текущим EntityManager.

AfterUpdateEntityListener

Метод onAfterUpdate() вызывается после изменения записи в БД, но до коммита транзакции. В данном методе нельзя модифицировать текущий персистентный контекст, однако можно производить изменения в БД с помощью QueryRunner.

BeforeDeleteEntityListener

Метод onBeforeDelete() вызывается перед удалением записи из БД (или в случае мягкого удаления - перед изменением записи). В данном методе возможны любые операции с текущим EntityManager.

AfterDeleteEntityListener

Метод onAfterDelete() вызывается после удаления записи из БД (или в случае мягкого удаления - после изменения записи), но до коммита транзакции. В данном методе нельзя модифицировать текущий персистентный контекст, однако можно производить изменения в БД с помощью QueryRunner.

Entity Listener может быть как обычным классом Java, так и управляемым бином. В последнем случае в нем можно использовать инжекцию:

@ManagedBean("cuba_MyEntityListener")
public class MyEntityListener implements
        BeforeInsertEntityListener<MyEntity>,
        BeforeUpdateEntityListener<MyEntity> {

    @Inject
    protected Persistence persistence;

    @Override
    public void onBeforeInsert(MyEntity entity) {
        EntityManager em = persistence.getEntityManager();
        ...
    }

    @Override
    public void onBeforeUpdate(MyEntity entity) {
        EntityManager em = persistence.getEntityManager();
        ...
    }
}

Entity Listener может быть задан 2-мя способами:

  • Статически - имена классов слушателей, или, если слушатель является бином, имена бинов, указываются в аннотации @Listeners на классе сущности:

    @Entity(...)
    @Table(...)
    @Listeners("cuba_MyEntityListener")
    public class MyEntity extends StandardEntity {
        ...
    }
  • Динамически - класс сущности и класс слушателя, или, если слушатель является бином, имя бина, передаются в метод addListener() бина EntityListenerManager. Пример динамического добавления слушателя рассматривается в разделе рецептов разработки: Раздел 5.8.4, «Выполнение кода на старте приложения».

Для всех экземпляров некоторого класса сущности извлекается из контекста Spring или создается и кэшируется один экземпляр слушателя определенного типа, поэтому слушатель не должен иметь состояния.

Если для сущности объявлены несколько слушателей одного типа (например, аннотациями класса сущности и его предков, плюс динамически), то их вызов будет выполняться в следующем порядке:

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

  2. После всех предков вызываются динамически добавленные слушатели данного класса, затем статически назначенные.

4.4.5. Управление транзакциями

В данном разделе рассмотрены различные аспекты управления транзакциями в CUBA-приложениях.

4.4.5.1. Программное управление транзакциями

Программное управление транзакциями осуществляется с помощью интерфейса com.haulmont.cuba.core.Transaction, ссылку на который можно получить методами createTransaction() или getTransaction() интерфейса инфраструктуры Persistence .

Метод createTransaction() создает новую транзакцию и возвращает интерфейс Transaction. Последующие вызовы методов commit(), commitRetaining(), end() этого интерфейса управляют созданной транзакцией. Если в момент создания существовала другая транзакция, то она будет приостановлена, и возобновлена после завершения созданной.

Метод getTransaction() вызывает либо создание новой, либо присоединение к текущей транзакции. Если в момент вызова существовала активная транзакция, то метод успешно завершается, и последующие вызовы commit(), commitRetaining(), end() не оказывают никакого влияния на существующую транзакцию. Однако если end() вызван без предварительного вызова commit(), то текущая транзакция помечается как RollbackOnly.

Пример ручного управления транзакцией:

@Inject
private Persistence persistence;
...
Transaction tx = persistence.createTransaction();
try {
    EntityManager em = persistence.getEntityManager();
    Customer customer = new Customer();
    customer.setName("John Smith");
    em.persist(customer);

    tx.commit();
} finally {
    tx.end();
}

Интерфейс Transaction имеет также метод execute(), принимающий на вход класс-действие, которое нужно выполнить в данной транзакции. Это позволяет организовать управление транзакциями в функциональном стиле, например:

persistence.createTransaction().execute(new Transaction.Runnable() {
    public void run(EntityManager em) {
        // transactional code here
    }
});

Если транзакционный блок должен вернуть результат, класс-действие должен реализовывать интерфейс Transaction.Callable. Если результат не требуется, как в приведенном примере, то класс-действие удобно наследовать от абстрактного класса Transaction.Runnable.

Следует иметь в виду, что метод execute() у некоторого экземпляра Transaction можно вызвать только один раз, так как после выполнения кода класса-действия транзакция завершается.

4.4.5.2. Декларативное управление транзакциями

Любой метод управляемого бина Middleware можно пометить аннотацией @org.springframework.transaction.annotation.Transactional, что вызовет автоматическое создание транзакции при вызове этого метода. В таком методе не нужно вызывать Persistence.createTransaction(), а можно сразу получать EntityManager и работать с ним.

Для аннотации @Transactional можно указать параметры. Основным параметром является режим создания транзакции - Propagation. Значение REQUIRED соответствует getTransaction(), значение REQUIRES_NEW - createTransaction(). По умолчанию REQUIRED.

Декларативное управление транзакциями позволяет уменьшить количество boilerplate кода, однако имеет следующий недостаток: коммит транзакции происходит вне прикладного кода, что часто затрудняет отладку, т.к. скрывается момент отправки изменений в БД и перехода сущностей в состояние Detached. Кроме того, следует иметь в виду, что декларативная разметка сработает только в случае вызова метода контейнером, т.е. вызов транзакционного метода из другого метода того же самого объекта не приведет к старту транзакции.

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

4.4.5.3. Примеры взаимодействия транзакций

4.4.5.3.1. Откат вложенной транзакции

Если вложенная транзакция создана через getTransaction(), то ее откат приведет к невозможности коммита охватывающей транзакции. Например:

void methodA() {
    Transaction tx = persistence.createTransaction();
    try {
        // (1) вызываем метод, создающий вложенную транзакцию
        methodB();

        // (4) в этот момент будет выброшено исключение, т.к. транзакция
        //     помечена как rollback only
        tx.commit();
    } finally {
        tx.end();
    }
}

void methodB() {
    Transaction tx = persistence.getTransaction();
    try {
        // (2) допустим здесь возникло исключение
        tx.commit();
    } catch (Exception e) {
        // (3) обрабатываем его и выходим
        return;
    } finally {
        tx.end();
    }
}

Если же транзакция в methodB() будет создана через createTransaction(), то ее откат не окажет никакого влияния на коммит охватывающей транзакции в methodA().

4.4.5.3.2. Чтение и изменение данных во вложенной транзакции

Рассмотрим сначала зависимую вложенную транзакцию, создаваемую через getTransaction():

void methodA() {
    Transaction tx = persistence.createTransaction();
    try {
        EntityManager em = persistence.getEntityManager();

        // (1) загружаем сущность, в которой name == "old name"
        Employee employee = em.find(Employee.class, id);
        assertEquals("old name", employee.getName());

        // (2) присваиваем новое значение полю
        employee.setName("name A");

        // (3) вызываем метод, создающий вложенную транзакцию
        methodB();

        // (8) здесь происходит коммит изменений в БД, и в ней
        //     окажется значение "name B"
        tx.commit();

    } finally {
        tx.end();
    }
}

void methodB() {
    Transaction tx = persistence.getTransaction();
    try {
        // (4) получаем тот же экземпляр EntityManager, что и methodA
        EntityManager em = persistence.getEntityManager();

        // (5) загружаем сущность с тем же идентификатором
        Employee employee = em.find(Employee.class, id);

        // (6) значение поля новое, т.к. мы работаем с тем же
        //     персистентным контекстом, и обращения к БД вообще
        //     не происходит
        assertEquals("name A", employee.getName());
        employee.setName("name B");

        // (7) в этот момент реально коммита не происходит
        tx.commit();
    } finally {
        tx.end();
    }
}

Теперь рассмотрим тот же самый пример с независимой вложенной транзакцией, создаваемой через createTransaction():

void methodA() {
    Transaction tx = persistence.createTransaction();
    try {
        EntityManager em = persistence.getEntityManager();

        // (1) загружаем сущность, в которой name == "old name"
        Employee employee = em.find(Employee.class, id);
        assertEquals("old name", employee.getName());

        // (2) присваиваем новое значение полю
        employee.setName("name A");

        // (3) вызываем метод, создающий вложенную транзакцию
        methodB();

        // (8) здесь возникнет исключение из-за оптимистичной блокировки
        //     и коммит не пройдет вообще
        tx.commit();

    } finally {
        tx.end();
    }
}

void methodB() {
    Transaction tx = persistence.createTransaction();
    try {
        // (4) создается новый экземпляр EntityManager, т.к. это
        //     новая транзакция
        EntityManager em = persistence.getEntityManager();

        // (5) загружаем сущность с тем же идентификатором
        Employee employee = em.find(Employee.class, id);

        // (6) значение поля старое, т.к. произошла загрузка из БД
        //     старого экземпляра сущности
        assertEquals("old name", employee.getName());

        employee.setName("name B");

        // (7) здесь происходит коммит изменений в БД, и в ней
        //     окажется значение "name B"
        tx.commit();

    } finally {
        tx.end();
    }
}

В последнем случае исключение в точке (8) возникнет, только если сущность является оптимистично блокируемой, т.е. если она реализует интерфейс Versioned.

4.4.5.4. Таймаут транзакции

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

При программном управлении транзакциями таймаут включается путем передачи объекта TransactionParams в метод Persistence.createTransaction(). Например:

Transaction tx = persistence.createTransaction(new TransactionParams().setTimeout(2));

При декларативном управлении транзакциями используется параметр timeout аннотации @Transactional, например:

@Transactional(timeout = 2)
public void someServiceMethod() {
...

Таймаут по умолчанию может быть задан в свойстве приложения cuba.defaultQueryTimeoutSec .

4.4.5.4.1. Особенности реализации для различных СУБД

PostgreSQL

К сожалению, JDBC драйвер PostgreSQL не поддерживает метод setQueryTimeout() интерфейса java.sql.Statement, поэтому в начале каждой транзакции, для которой определен таймаут (любым способом, включая ненулевое значение свойства cuba.defaultQueryTimeoutSec ), выполняется дополнительный оператор в БД: set local statement_timeout to {value}. При этом в случае превышения таймаута запрос будет прерван самим сервером БД.

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

  • Таймаут по умолчанию устанавливать не на Middleware с помощью свойства cuba.defaultQueryTimeoutSec, а на самом сервере PostgreSQL в файле postgresql.conf, например, statement_timeout = 3000 (это в миллисекундах).

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

Microsoft SQL Server

Драйвер JTDS поддерживает метод setQueryTimeout() интерфейса java.sql.Statement, поэтому для EntityManager просто устанавливается стандартное свойство javax.persistence.query.timeout, которое соответствующим образом влияет на JDBC запросы.

4.5. Универсальный пользовательский интерфейс

Подсистема универсального пользовательского интерфейса (Generic UI, GUI) позволяет разрабатывать экраны пользовательского интерфейса, используя XML и Java. Созданные таким образом экраны одинаково работоспособны в двух стандартных клиентских блоках: Web Client и Desktop Client.

Рисунок 15. Структура универсального пользовательского интерфейса

Структура универсального пользовательского интерфейса

Здесь в центре изображены основные составляющие экранов универсального пользовательского интерфейса:

  • XML-дескрипторы - файлы XML, содержащие информацию об источниках данных и компоновке экрана

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

Код экранов приложения, расположенный в модуле gui, взаимодействует с интерфейсами визуальных компонентов (VCL Interfaces), реализованными по-отдельности в модулях web и desktop базового проекта cuba. Для Web Client реализация основана на фреймворке Vaadin, для Desktop Client – на фреймворке Java Swing.

Библиотека визуальных компонентов (Visual Components Library, VCL) содержит большой набор готовых компонентов для отображения данных.

Механизм источников данных (Datasources) предоставляет унифицированный интерфейс, обеспечивающий функционирование связанных с данными визуальных компонентов.

Инфраструктура клиента (Infrastructure) включает в себя главное окно приложения, механизмы отображения и взаимодействия экранов UI, а также средства взаимодействия со средним слоем.

4.5.1. Экраны

Экран универсального пользовательского интерфейса состоит из XML-дескриптора и класса контроллера. Дескриптор содержит ссылку на класс контроллера.

Для того чтобы экран можно было вызывать из главного меню или из Java кода (например, из контроллера другого экрана), XML-дескриптор должен быть зарегистрирован в файле screens.xml проекта.

Главное меню приложения формируется отдельно для Web Client и Desktop Client на основе файлов menu.xml , расположенных соответственно в модулях web и desktop проекта.

4.5.1.1. Типы экранов

В данном разделе рассматриваются основные типы экранов:

4.5.1.1.1. Фрейм

Фреймы представляют собой части экранов, которые применяются для декомпозиции и многократного использования.

Для подключения фрейма в XML экрана используется элемент iframe c указанием либо пути к файлу XML фрейма, либо идентификатора фрейма, если он зарегистрирован в screens.xml .

Контроллер фрейма должен быть унаследован от класса AbstractFrame.

Правила взаимодействия экрана и вложенного в него фрейма:

  • Из экрана обращаться к компонентам фрейма можно через точку: frame_id.component_id

  • Из контроллера фрейма получить компонент экрана можно обычным вызовом getComponent(component_id), но только в том случае, если компонент с таким именем не объявлен в самом фрейме. То есть компоненты фрейма маскируют компоненты экрана.

  • Из фрейма получить источник данных экрана можно простым вызовом getDsContext().get(ds_id) или инжекцией, либо в запросе ds$ds_id, но только в том случае, если источник данных с таким именем не объявлен в самом фрейме (аналогично компонентам).

  • Из экрана получить источник данных фрейма можно только через итерацию по getDsContext().getChildren()

При коммите экрана вызывается также коммит измененных источников данных фрейма.

4.5.1.1.2. Простой экран

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

Идентификатор экрана в файле screens.xml может быть произвольного вида.

Контроллер простого экрана должен быть унаследован от класса AbstractWindow.

4.5.1.1.3. Экран выбора

Экран выбора (lookup) отличается от простого экрана тем, что при вызове методом openLookup() отображает внизу панель с кнопками, позволяющими передать вызывающему коду экземпляр выбранной в данный момент в списке сущности. При вызове методом openWindow() или, например, из главного меню, панель с кнопками выбора не отображается.

В метод openLookup() передается объект с интерфейсом Window.Lookup.Handler. Метод handleLookup() этого объекта вызывается экраном, и ему передается коллекция выбранных пользователем экземпляров сущности. Тем самым вызывающий код получает из экрана выбранные экземпляры.

Экраны выбора рекомендуется использовать для отображения списков сущностей. Визуальные компоненты, предназначенные для отображения и редактирования ссылок между сущностями (такие как PickerField , LookupPickerField , SearchPickerField ), вызывают экраны выбора для поиска связанных сущностей.

Для корректной работы стандартных действий идентификатор экрана выбора в файле screens.xml должен иметь вид {имя_сущности}.lookup, например, sales$Customer.lookup.

Контроллер экрана выбора должен быть унаследован от класса AbstractLookup. В XML экрана в атрибуте lookupComponent должен быть указан компонент (например, Table ), из которого будет взят экземпляр сущности при выборе.

4.5.1.1.4. Экран редактирования

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

Для корректной работы стандартных действий идентификатор экрана редактирования в файле screens.xml должен иметь вид {имя_сущности}.edit, например, sales$Customer.edit.

Контроллер экрана редактирования должен быть унаследован от класса AbstractEditor. В XML экрана в атрибуте datasource указывается источник данных, в который проставляется редактируемый экземпляр сущности. Для отображения действий, выполняющих коммит или отмену изменений, в XML можно использовать следующие стандартные фреймы с кнопками:

  • editWindowActions (файл com/haulmont/cuba/gui/edit-window.actions.xml) - содержит кнопки OK и Cancel

  • extendedEditWindowActions (файл com/haulmont/cuba/gui/extended-edit-window.actions.xml) - содержит кнопки OK & Close, OK и Cancel

В экране редактирования неявно создаются следующие действия:

  • windowCommitAndClose (соответствует константе Window.Editor.WINDOW_COMMIT_AND_CLOSE) - действие, выполняющее коммит изменений в базу данных и закрывающее экран. Создается при наличии в экране визуального компонента с идентификатором windowCommitAndClose, в частности, при использовании вышеописанного стандартного фрейма extendedEditWindowActions отображается кнопкой OK & Close.

  • windowCommit (соответствует константе Window.Editor.WINDOW_COMMIT) - действие, выполняющее коммит изменений в базу данных. При отсутствии действия windowCommitAndClose после коммита закрывает экран. Создается всегда, и при наличии в экране вышеописанных стандартных фреймов отображается кнопкой OK.

  • windowClose (соответствует константе Window.Editor.WINDOW_CLOSE) - действие, закрывающее экран без коммита изменений. Создается всегда, и при наличии в экране вышеописанных стандартных фреймов отображается кнопкой Cancel.

Таким образом, если в экран добавлен фрейм editWindowActions, то кнопка OK коммитит изменения и закрывает экран, а кнопка Cancel - закрывает без коммита. Если же добавлен фрейм extendedEditWindowActions, то кнопка OK только коммитит изменения, оставляя экран открытым, кнопка OK & Close коммитит и закрывает экран, кнопка Cancel - закрывает без коммита.

Вместо стандартных фреймов для отображения действий можно использовать произвольные компоненты, например, LinkButton .

4.5.1.2. XML-дескриптор

XML-дескриптор - это файл формата XML, описывающий источники данных и расположение визуальных компонентов экрана.

Схема XML доступна по адресу http://schemas.haulmont.com/cuba/5.6/window.xsd

Рассмотрим структуру дескриптора.

window − корневой элемент.

Атрибуты window:

  • class − имя класса контроллера

  • messagesPackпакет сообщений данного экрана, который будет использован при получении локализованных строк без указания пакета из XML-дескриптора и из контроллера методом getMessage()

  • caption − заголовок экрана, может содержать ссылку на сообщение из вышеуказанного пакета, например,

    caption="msg://caption"
  • focusComponent − идентификатор компонента, который получит фокус ввода при отображении экрана

  • lookupComponent - обязательный для экрана выбора атрибут, задающий идентификатор визуального компонента, из которого будет выбран экземпляр сущности. Поддерживаются компоненты следующих типов (и их наследников):

    • Table

    • Tree

    • LookupField

    • PickerField

    • OptionsGroup

  • datasource - обязательный для экрана редактирования атрибут, задающий идентификатор источника данных, в который будет проставлен экземпляр редактируемой сущности.

Элементы window:

  • metadataContext − элемент для инициализации представлений (views), необходимых данному экрану. Предпочтительным является определение всех представлений в одном общем файле views.xml , так как все описатели представлений разворачиваются в один общий репозиторий, и при рассредоточении описателей по разным файлам трудно обеспечить уникальность имен.

  • dsContext − определяет источники данных данного экрана.

  • actions - определяет список действий данного экрана.

  • timers - определяет список таймеров данного экрана.

  • companions - определяет список классов-компаньонов данного контроллера

    Элементы companions:

    • web - задает компаньон, реализованный в модуле web

    • desktop - задает компаньон, реализованный в модуле desktop

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

  • layout − корневой элемент компоновки экрана. Является сам по себе контейнером с вертикальным расположением компонентов, аналогичным vbox .

    Атрибуты layout:

4.5.1.3. Контроллер экрана

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

Контроллер должен быть унаследован от одного из следующих базовых классов:

Если экрану не нужна никакая дополнительная логика, то в качестве контроллера можно использовать сам базовый класс AbstractWindow, AbstractLookup или AbstractEditor, указав его в XML-дескрипторе (эти классы на самом деле не являются абстрактными в смысле невозможности создания экземпляров). Для фрейма класс контроллера можно не указывать вообще.

Класс контроллера должен быть зарегистрирован в XML-дескрипторе экрана в атрибуте class корневого элемента window.

Рисунок 16. Базовые классы контроллеров

Базовые классы контроллеров

4.5.1.3.1. AbstractFrame

AbstractFrame является корнем иерархии классов контроллеров. Рассмотрим его основные методы:

  • init() - вызывается фреймворком после создания всего дерева компонентов, описанного XML-дескриптором, но до отображения экрана.

    В метод init() из вызывающего кода передается мэп параметров, которые могут быть использованы внутри контроллера. Эти параметры могут быть переданы как из кода контроллера вызывающего экрана (в методе openWindow(), openLookup() или openEditor()), так и установлены в файле регистрации экранов screens.xml .

    Метод init() следует имплементировать при необходимости инициализации компонентов экрана, например:

    @Inject
    private Table someTable;
    
    @Override
    public void init(Map<String, Object> params) {
      someTable.addGeneratedColumn("someColumn", new Table.ColumnGenerator<Colour>() {
          @Override
          public Component generateCell(Colour entity) {
              ...
          }
      });
    }
  • getMessage(), formatMessage() - методы получения локализованных сообщений из пакета, заданного для экрана в XML-дескрипторе. Представляют собой просто короткие варианты вызова одноименных методов интерфейса Messages .

  • getDialogParams() - получить объект DialogParams для установки параметров отображения диалоговых окон (высота, ширина и пр.). Значения, установленные в этом объекте, влияют на следующий экран, открываемый в режиме модального диалога (WindowManager.OpenType.DIALOG). После отображения диалога они сбрасываются в значения по умолчанию.

    Таким образом, устанавливать значения в DialogParams необходимо непосредственно перед вызовом другого экрана в режиме диалога методами openWindow(), openLookup(), openEditor(). Например:

    getDialogParams().setWidth(400);
    openEditor("sales$Customer.edit", customer, WindowManager.OpenType.DIALOG);

    Если же сам текущий экран открывается в режиме модального диалога, то можно управлять параметрами его отображения, устанавливая параметры DialogParams в его методе init(). При этом установленные в init() параметры имеют приоритет над установленными в вызывающем коде.

  • openFrame() - загрузить фрейм по идентификатору, зарегистрированному в screens.xml , и, если в метод передан компонент-контейнер, отобразить его внутри контейнера. Возвращается контроллер фрейма. Например:

    @Inject
    private BoxLayout container;
    
    @Override
    public void init(Map<String, Object> params) {
      SomeFrame frame = openFrame(container, "someFrame");
      frame.setHeight("100%");
      frame.someInitMethod();
    }

    Контейнер не обязательно сразу передавать в метод openFrame(), вместо этого можно загрузить фрейм, а затем добавить его в нужный контейнер:

    @Inject
    private BoxLayout container;
    
    @Override
    public void init(Map<String, Object> params) {
      SomeFrame frame = openFrame(null, "someFrame");
      frame.setHeight("100%");
      frame.someInitMethod();
      container.add(frame);
    }
  • openWindow(), openLookup(), openEditor() - открыть соответственно простой экран, экран выбора или редактирования. Методы возвращают контроллер созданного экрана.

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

    CustomerEdit editor = openEditor("sales$Customer.edit", customer, WindowManager.OpenType.THIS_TAB);
    editor.addListener(new CloseListener() {
      @Override
      public void windowClosed(String actionId) {
          // do something
      }
    });
  • showMessageDialog() - отобразить диалоговое окно с сообщением.

  • showOptionDialog() - отобразить диалоговое окно с сообщением и возможностью выбора пользователем некоторых действий. Действия задаются массивом объектов типа Action , которые в диалоге отображаются посредством соответствующих кнопок.

    Для отображения стандартных кнопок типа OK, Cancel и других рекомендуется использовать объекты типа DialogAction, например:

    showOptionDialog("PLease confirm", "Are you sure?",
          MessageType.CONFIRMATION,
          new Action[] {
                  new DialogAction(DialogAction.Type.YES) {
                      @Override
                      public void actionPerform(Component component) {
                          // do something
                      }
                  },
                  new DialogAction(DialogAction.Type.NO);
          });
  • showNotification() - отобразить всплывающее окно с сообщением.

  • showWebPage() - открыть указанную веб-страницу в браузере.

4.5.1.3.2. AbstractWindow

AbstractWindow является наследником AbstractFrame , и определяет следующие собственные методы:

  • ready() - шаблонный метод, который можно имплементировать в контроллере для перехвата момента открытия экрана. Метод ready() вызывается фреймворком после метода init() непосредственно перед показом экрана в главном окне приложения.

  • validateAll() - валидация экрана. Реализация по умолчанию вызывает метод validate() у всех компонентов экрана, реализующих интерфейс Component.Validatable, накапливает информацию об исключениях, и если таковые имеются, выводит соответствующее сообщение и возвращает false, иначе возвращает true.

    Данный метод следует переопределять только в том случае, если необходимо полностью заменить стандартную процедуру валидации экрана. Если же нужно только дополнить ее, достаточно определить специальный шаблонный метод postValidate().

  • postValidate() - шаблонный метод, который можно имплементировать в контроллере для дополнительной валидации экрана. Получаемый методом объект ValidationErrors используется для добавления информации об ошибках валидации, которая будет отображена совместно с ошибками стандартной валидации. Например:

    private Pattern pattern = Pattern.compile("\\d");
    
    @Override
    protected void postValidate(ValidationErrors errors) {
      if (getItem().getAddress().getCity() != null) {
          if (pattern.matcher(getItem().getAddress().getCity()).find()) {
              errors.add("City name can't contain digits");
          }
      }
    }
  • close() - закрыть данный экран.

    Метод принимает строковое значение, передаваемое далее в шаблонный метод preClose() и слушателям CloseListener. Таким образом, заинтересованный код может получить информацию о причине закрытия экрана от кода, инициирующего закрытие. В частности, в экранах редактирования сущностей при закрытии экрана после коммита изменений рекомендуется использовать константу Window.COMMIT_ACTION_ID, без коммита изменений - константу Window.CLOSE_ACTION_ID.

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

    Вариант метода close() с параметром force = true закрывает экран без вызова preClose() и без предупреждения, независимо от наличия несохраненных изменений.

    Метод close() возвращает true, если экран был успешно закрыт, и false - если закрытие было прервано.

  • preClose() - шаблонный метод, который можно имплементировать в контроллере для перехвата момента закрытия экрана. Метод получает строковое значение, указанное инициатором закрытия при вызове метода close().

    Если метод preClose() возвращает false, то процесс закрытия экрана прерывается.

4.5.1.3.3. AbstractLookup

AbstractLookup базовый класс контроллеров экранов выбора, является наследником AbstractWindow , и определяет следующие собственные методы:

  • setLookupComponent() - установить компонент, из которого будет производиться выбор экземпляров сущности.

    Как правило, компонент выбора устанавливается в XML-дескрипторе экрана, и вызывать данный метод в прикладном коде нет необходимости.

  • setLookupValidator() - установить для экрана объект типа Window.Lookup.Validator, метод validate() которого вызывается фреймворком перед тем как вернуть выбранные экземпляры сущностей. Если validate() возвращает false, процесс выбора и закрытия экрана прерывается.

    По умолчанию валидатор не установлен.

4.5.1.3.4. AbstractEditor

AbstractEditor − базовый класс контроллеров экранов редактирования, является наследником AbstractWindow .

При создании конкретного класса контроллера рекомендуется параметризовать AbstractEditor типом редактируемой сущности. При этом методы getItem() и initItem() будут работать с конкретным типом сущности и прикладному коду не потребуется дополнительных приведений типов. Например:

public class CustomerEdit extends AbstractEditor<Customer> {

  @Override
  protected void initItem(Customer item) {
  ...

AbstractEditor определяет следующие собственные методы:

  • getItem() - возвращает экземпляр редактируемой сущности, установленный в главном источнике данных экрана (т.е. указанном в атрибуте datasource корневого элемента XML-дескриптора).

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

    Изменения, вносимые в экземпляр, возвращаемый getItem(), отражаются на состоянии источника данных, и будут отправлены на Middleware при коммите экрана.

    Следует иметь в виду, что getItem() возвращает значение только после инициализации экрана методом setItem(). До этого момента, например, в методах init() и initItem(), данный метод возвращает null.

    Однако в методе init() экземпляр сущности, переданный в openEditor(), можно получить из параметров следующим образом:

    @Override
    public void init(Map<String, Object> params) {
      Customer item = WindowParams.ITEM.getEntity(params);
      // do something
    }

    В метод initItem() экземпляр передается явно и нужного типа.

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

  • setItem() - вызывается фреймворком при открытии экрана методом openEditor() для установки редактируемого экземпляра сущности в главном источнике данных. В момент вызова созданы все компоненты и источники данных экрана, и отработал метод init() контроллера.

    Для инициализации экрана редактирования вместо переопределения setItem() рекомендуется имплементировать специальные шаблонные методы initItem() и postInit().

  • initNewItem() - шаблонный метод, вызываемый фреймворком перед установкой редактируемого экземпляра сущности в главном источнике данных.

    Метод initNewItem() вызывается только для нового, только что созданного экземпляра сущности. Если редактируется detached экземпляр, метод не вызывается.

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

    @Inject
    private UserSession userSession;
    
    @Override
    protected void initNewItem(Complaint item) {
      item.setOpenedBy(userSession.getUser());
      item.setStatus(ComplaintStatus.OPENED);
    }

    Более сложный пример использования initNewItem() приведен в разделе рецептов разработки.

  • postInit() - шаблонный метод, вызываемый фреймворком сразу после установки редактируемого экземпляра сущности в главном источнике данных. Во время выполнения данного метода можно вызывать getItem(), который будет возвращать новый или перезагруженный при инициализации экрана экземпляр сущности.

    Данный метод можно имплементировать в контроллере для окончательной инициализации экрана, например:

    @Inject
    protected EntityDiffViewer diffFrame;
    
    @Override
    protected void postInit() {
      if (!PersistenceHelper.isNew(getItem())) {
          diffFrame.loadVersions(getItem());
      }
    }
  • commit() - валидировать экран и отправить изменения через DataSupplier на Middleware.

    Если используется вариант метода с параметром validate = false, то валидация перед коммитом не производится.

    Данный метод не рекомендуется переопределять, лучше использовать специальные шаблонные методы postValidate(), preCommit() и postCommit().

  • commitAndClose() - валидировать экран, отправить изменения на Middleware и закрыть экран. В метод preClose() и зарегистрированным слушателям CloseListener будет передано значение константы Window.COMMIT_ACTION_ID.

    Данный метод не рекомендуется переопределять, лучше использовать специальные шаблонные методы postValidate(), preCommit() и postCommit().

  • preCommit() - шаблонный метод, вызываемый фреймворком в процессе коммита изменений, после того как валидация завершена успешно и перед отправкой данных на Middleware.

    Данный метод можно имплементировать в контроллере. Если метод возвращает false, процесс коммита (и закрытия экрана, если был вызван commitAndClose()), прерывается. Например:

    @Override
    protected boolean preCommit() {
      if (somethingWentWrong) {
          showNotification("Something went wrong", NotificationType.WARNING);
          return false;
      }
      return true;
    }
  • postCommit() - шаблонный метод, вызываемый фреймворком на финальной стадии коммита изменений. Параметры метода:

    • committed - установлен в true, если в экране действительно были изменения, и они отправлены на Middleware;

    • close - установлен в true, если экран после коммита будет закрыт.

    Реализация метода по умолчанию, если экран не закрывается, отображает сообщение об успешном коммите изменений и вызывает метод postInit().

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

    @Inject
    private Datasource<Driver> driverDs;
    @Inject
    private EntitySnapshotService entitySnapshotService;
    
    @Override
    protected boolean postCommit(boolean committed, boolean close) {
      if (committed) {
          entitySnapshotService.createSnapshot(driverDs.getItem(), driverDs.getView());
      }
      return super.postCommit(committed, close);
    }

Далее приведены диаграммы последовательностей инициализации и различных вариантов коммита экрана редактирования.

Рисунок 17. Инициализация экрана редактирования

Инициализация экрана редактирования

Рисунок 18. Коммит и закрытие экрана с фреймом editWindowActions

Коммит и закрытие экрана с фреймом editWindowActions

Рисунок 19. Коммит экрана с фреймом extendedEditWindowActions

Коммит экрана с фреймом extendedEditWindowActions

Рисунок 20. Коммит и закрытие экрана с фреймом extendedEditWindowActions

Коммит и закрытие экрана с фреймом extendedEditWindowActions

4.5.1.3.5. Инжекция зависимостей контроллеров

В контроллерах можно использовать Dependency Injection для получения ссылок на используемые объекты. Для этого нужно объявить либо поле соответствующего типа, либо метод доступа на запись (setter) с соответствующим типом результата, и добавить ему одну из следующих аннотаций:

  • @Inject - простейший вариант, поиск объекта для инжекции будет произведен по типу поля/метода и по имени, эквивалентному имени поля либо имени атрибута (по правилам JavaBeans) для метода

  • @Named("someName") - вариант с явным указанием имени искомого объекта

Инжектировать в контроллеры можно следующие объекты:

  • Визуальные компоненты данного экрана, определенные в XML-дескрипторе. Если тип атрибута унаследован от Component, в текущем экране будет произведен поиск компонента с соответствующим именем.

  • Действия, определенные в XML-дескрипторе - см. Раздел 4.5.4, «Действия. Интерфейс Action»

  • Источники данных, определенные в XML-дескрипторе. Если тип атрибута унаследован от Datasource, в текущем экране будет произведен поиск источника данных с соответствующим именем.

  • UserSession. Если тип атрибута - UserSession , будет инжектирован объект текущей пользовательской сессии.

  • DsContext. Если тип атрибута - DsContext, будет инжектирован DsContext текущего экрана.

  • WindowContext. Если тип атрибута - WindowContext, будет инжектирован WindowContext текущего экрана.

  • DataSupplier. Если тип атрибута - DataSupplier , будет инжектирован соответствующий экземпляр.

  • Любой бин, определенный в контексте данного клиентского блока приложения, в том числе:

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

С помощью специальной аннотации @WindowParam можно инжектировать в контроллер параметры, передаваемые в мэп метода init(). Аннотация имеет атрибут name, в котором указывается имя параметра (ключ в мэп), и опциональный атрибут required. Если required = true, то при отсутствии в мэп соответствующего параметра в лог выводится сообщение с уровнем WARNING.

Пример инжекции объекта типа Job, передаваемого в метод init() контроллера:

@WindowParam(name = "job", required = true)
protected Job job;
4.5.1.3.6. Компаньоны контроллеров

Базовые классы контроллеров расположены в модуле gui базового проекта cuba и не содержат ссылок на классы реализации визуальных компонентов (Swing или Vaadin), что дает возможность использовать их в клиентах обоих типов. Вместо этого базовые классы контроллеров реализуют дополнительный интерфейс Window.Wrapper и делегируют выполнение "обернутому" окну.

В то же время конкретные классы контроллеров могут быть расположены как в модуле gui, так и в web или desktop, в зависимости от применяемых в проекте клиентских блоков и специфики экрана. Если контроллер является универсальным, но для разных типов клиента требуется дополнительная функциональность, ее можно определить в так называемых классах-компаньонах.

Класс-компаньон располагается в модуле клиента соответствующего типа (web или desktop) и реализует интерфейс, задаваемый в использующем его контроллере. Класс компаньона задается в элементе companions XML-дескриптора экрана. Контроллер может получить ссылку на экземпляр компаньона с помощью инжекции или вызовом getCompanion(), и в нужный момент передать ему управление, например, для дополнительной инициализации визуальных компонентов специфичным для данного типа клиента способом.

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

public class CustomerBrowse extends AbstractLookup {

  public interface Companion {
      void initTable(Table table);
  }

  @Inject
  protected Table table;

  @Inject
  protected Companion companion;

  @Override
  public void init(Map<String, Object> params) {
      if (companion != null) {
          companion.initTable(table);
      }
  }
}

В модулях web и desktop создаем соответствующие классы реализации компаньона:

public class WebCustomerBrowseCompanion implements CustomerBrowse.Companion {
  @Override
  public void initTable(Table table) {
      com.vaadin.ui.Table webTable = (com.vaadin.ui.Table) WebComponentsHelper.unwrap(table);
      // do something specific to Vaadin table
  }
}
public class DesktopCustomerBrowseCompanion implements CustomerBrowse.Companion {
  @Override
  public void initTable(Table table) {
      javax.swing.JTable desktopTable = (javax.swing.JTable) DesktopComponentsHelper.unwrap(table);
      // do something specific to Swing table
  }
}

И регистрируем классы реализации компаньона в XML-дескрипторе экрана:

<window ...
      class="com.company.sample.gui.customers.CustomerBrowse">
  <companions>
      <web class="com.company.sample.web.customers.WebCustomerBrowseCompanion"/>
      <desktop class="com.company.sample.desktop.customers.DesktopCustomerBrowseCompanion"/>
  </companions>
  <dsContext>...</dsContext>
  <layout>...</layout>
</window>

Так как классы-компаньоны расположены в web и desktop модулях, в них можно использовать метод unwrap() классов WebComponentsHelper и DesktopComponentsHelper для извлечения из интерфейса Table ссылок на реализующие таблицу Vaadin и Swing компоненты, и работать с ними непосредственно.

4.5.2. Библиотека визуальных компонентов

Компоненты

Контейнеры

Разное

4.5.2.1. Компоненты

Рисунок 21. Диаграмма компонентов

Диаграмма компонентов

Component − предок всех визуальных компонентов. Он содержит базовые атрибуты, позволяющие идентифицировать компонент и располагать его на экране.

4.5.2.1.1. Button

Кнопка (Button) − компонент, обеспечивающий выполнение действия при нажатии.

XML-имя компонента: button

Компонент кнопки реализован для блоков Web Client и Desktop Client.

Кнопка может содержать текст или пиктограмму (или и то и другое). На рисунке ниже отображены разные виды кнопок.

Пример кнопки с названием, взятым из пакета локализованных сообщений, и с всплывающей подсказкой:

<button id="textButton" caption="msg://someAction" description="Press me"/>

Название кнопки задается с помощью атрибута caption, всплывающая подсказка − с помощью атрибута description.

Атрибут icon указывает на местоположение пиктограммы. Подробную информацию о том, где следует располагать файлы пиктограмм, можно прочитать в Раздел 4.5.7, «Создание темы приложения»

Пример создания кнопки с пиктограммой:

<button id="iconButton" caption="" icon="icons/save.png"/>

Основная функция кнопки − выполнить некоторое действие при нажатии на нее. Определить метод контроллера, который будет вызываться при нажатии на кнопку, можно с помощью атрибута invoke. Значением атрибута должно быть имя метода контроллера, удовлетворяющего следующим условиям:

  • Метод должен быть public.

  • Метод должен возвращать void.

  • Метод должен либо не иметь аргументов, либо иметь один аргумент типа Component. Если метод имеет аргумент Component, то при вызове в него будет передан экземпляр вызвавшей кнопки.

В качестве примера показано описание кнопки, вызывающей метод someMethod:

<button invoke="someMethod" caption="msg://someButton"/>

В контроллере экрана необходимо определить метод someMethod:

public void someMethod() {
//some actions
}

Атрибут invoke игнорируется, если для кнопки задан атрибут action. Атрибут action содержит имя действия, соответствующего данной кнопке.

Пример кнопки с атрибутом action:

<actions>
<action id="someAction" caption="msg://someAction"/>
</actions>
<layout>
<button action="someAction"/>

Кнопке можно назначить любое действие, имеющееся в каком-либо компоненте, реализующем интерфейс Component.ActionsHolder (это актуально для Table, GroupTable, TreeTable, Tree). Причем неважно, каким образом эти действия добавлены - декларативно в XML-дескрипторе или программно в контроллере. В любом случае для использования такого действия достаточно в атрибуте action указать через точку имя компонента и идентификатор нужного действия. Например, в следующем примере кнопке назначается действие create таблицы coloursTable:

<button action="coloursTable.create"/>

Действие для кнопки можно также создавать программно, в контроллере экрана, используя наследование от класса AbstractAction.

Если для Button установлен экземпляр Action, то кнопка возьмет из него следующие свои свойства: caption, description, icon, enable, visible. Свойства caption и description будут проставлены из действия только в том случае, если они не установлены в самом Button. Остальные перечисленные свойства действия имеют безусловный приоритет над свойствами кнопки. Если свойства действия меняются уже после установки этого Action для Button, то соответственно меняться будут и свойства Button, то есть кнопка слушает изменение свойств действия. В этом случае меняется и свойства caption и description, причем даже если они изначально были назначены на саму кнопку.

Атрибуты button:

4.5.2.1.2. Bulk Editor

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

XML-имя компонента: bulkEditor

Компонент реализован для блоков Web Client и Desktop Client.

Для использования Bulk Editor у таблицы или дерева должен быть задан атрибут multiselect="true".

Экран редактирования сущностей генерируется автоматически на основе заданного представления (содержащего только поля данной сущности, в том числе ссылки) и разрешений пользователя. Системные атрибуты в редакторе также не отображаются.

Атрибуты сущности в редакторе сортируются по алфавиту. По умолчанию они пусты. При коммите экрана заданные на экране непустые значения атрибутов проставляются всем выбранным экземплярам сущности.

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

Пример описания компонента bulkEditor для таблицы:

<table id="invoiceTable"
       multiselect="true"
       width="100%">
    <actions>
        <!-- ... -->
    </actions>
    <buttonsPanel>
        <!-- ... -->
        <bulkEditor for="invoiceTable"
                    exclude="customer"/>
    </buttonsPanel>

Атрибут for является обязательным. В нем указывается идентификатор таблицы или дерева, в данном случае - invoiceTable.

Атрибут exclude может содержать регулярное выражения для явного исключения определенных полей из списка редактируемых. Например: date|customer

Атрибуты BulkEditor:

4.5.2.1.3. CheckBox

Флажок (CheckBox) − компонент, имеющий два состояния: выбран, не выбран.

XML-имя компонента: checkBox.

Компонент CheckBox реализован для блоков Web Client и Desktop Client.

Пример флажка с надписью, взятой из пакета локализованных сообщений:

<checkBox id="accessField" caption="msg://accessFieldCaption"/>

Сброс или установка флажка изменяет его значение: Boolean.TRUE или Boolean.FALSE. Значение может быть получено с помощью метода getValue() и установлено с помощью метода setValue(). Если в setValue() передать null, то устанавливается значение Boolean.FALSE и флажок снимается.

Изменение значения флажка, так же как и любого другого компонента, реализующего интерфейс Field, можно отслеживать с помощью слушателя ValueListener. Например:

@Inject
private CheckBox accessField;

@Override
public void init(Map<String, Object> params) {
accessField.addListener(new ValueListener<Object>() {
    @Override
    public void valueChanged(Object source, String property, Object prevValue, Object value) {
        if (Boolean.TRUE.equals(value)) {
            showNotification("set", NotificationType.HUMANIZED);
        } else {
            showNotification("not set", NotificationType.HUMANIZED);
        }
    }
});
}

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

<dsContext>
<datasource id="customerDs" class="com.sample.sales.entity.Customer" view="_local"/>
</dsContext>
<layout>
<checkBox datasource="customerDs" property="active"/>

Как видно из примера, в экране описывается источник данных customerDs для некоторой сущности Покупатель (Customer), имеющей атрибут active. В компоненте checkBox в атрибуте datasource указывается ссылка на источник данных, а в атрибуте property − название атрибута сущности, значение которого должно быть отображено флажком. Атрибут должен быть типа Boolean. Значением атрибута может быть null, при этом флажок снимается.

Атрибуты checkBox:

4.5.2.1.4. DateField

Поле для отображения и ввода даты и времени. Представляет собой поле даты, внутри которого имеется кнопка с выпадающим календарем, а правее находится поле для ввода времени.

XML-имя компонента: dateField.

Компонент DateField реализован для блоков Web Client и Desktop Client.

  • Для создания поля даты, связанного с данными, необходимо использовать атрибуты datasource и property:

    <dsContext>
        <datasource id="orderDs" class="com.sample.sales.entity.Order" view="_local"/>
    </dsContext>
    <layout>
        <dateField datasource="orderDs" property="date"/>

    Как видно из примера, в экране описывается источник данных orderDs для некоторой сущности Заказ (Order), имеющей атрибут date. В компоненте ввода даты в атрибуте datasource указывается ссылка на источник данных, а в атрибуте property − название атрибута сущности, значение которого должно быть отображено в поле.

  • Если поле связано с атрибутом сущности, то оно автоматически принимает соответствующий вид:

  • Изменить формат представления даты и времени можно с помощью атрибута dateFormat. Значением атрибута может быть либо сама строка формата, либо ключ в пакете сообщений (если значение начинается с msg://).

    Формат задается по правилам класса SimpleDateFormat (http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html). Если в формате отсутствуют символы H или h, то поле времени не выводится.

    <dateField dateFormat="MM/yy" caption="msg://monthOnlyDateField"/>
  • Если для пользователя методом setTimeZone() задан часовой пояс, то DateField может преобразовывать значения типа timestamp между часовыми поясами сервера и пользователя. Если компонент привязан к атрибуту типа timestamp, часовой пояс автоматически берется из текущей пользовательской сессии. Если нет, то можно вызвать метод setTimeZone() в контроллере экрана, чтобы DateField выполнил необходимые преобразования.

  • Точность представления даты и времени можно определить с помощью атрибута resolution. Значение атрибута должно соответствовать перечислению DateField.ResolutionSEC, MIN, HOUR, DAY, MONTH, YEAR. По умолчанию - MIN, то есть до минут.

    Если resolution="DAY" и не указан атрибут dateFormat, то в качестве формата будет взят формат, указанный в главном пакете сообщений с ключом dateFormat.

    Если resolution="MIN" и не указан атрибут dateFormat, то в качестве формата будет взят формат, указанный в главном пакете сообщений с ключом dateTimeFormat.

    Ниже показано определения поля для ввода даты с точностью до месяца.

    <dateField resolution="MONTH" caption="msg://monthOnlyDateField"/>

.

DateField в основном предназначен для быстрого ввода с клавиатуры путем заполнения маски. Поэтому компонент поддерживает только форматы с цифрами и разделителями. Сложные форматы с текстовым представлением дня недели или месяца не будут работать.

Атрибуты dateField:

Элементы dateField:

4.5.2.1.5. Embedded

Компонент Embedded предназначен для вывода изображений и встраивания в экран произвольных веб-страниц.

XML-имя компонента: embedded

Компонент реализован для блоков Web Client и Desktop Client. В десктоп-клиенте поддерживается только вывод изображений.

Рассмотрим пример использования компонента для вывода изображения из файла, сохраненного в FileStorage.

  • Объявляем компонент в XML-дескрипторе экрана:

    <groupBox caption="Embedded" spacing="true"
          height="250px" width="250px" expand="embedded">
    <embedded id="embedded" width="100%"
              align="MIDDLE_CENTER"/>
    </groupBox>
  • В контроллере экрана инжектируем компонент и интерфейс FileStorageService. Затем в методе init() получаем из параметров экрана переданный из вызывающего кода FileDescriptor, загружаем соответствующий файл в байтовый массив, создаем для него ByteArrayInputStream и передаем в метод setSource() компонента:

    @Inject
    private Embedded embedded;
    
    @Inject
    private FileStorageService fileStorageService;
    
    @Override
    public void init(Map<String, Object> params) {
    FileDescriptor imageFile = (FileDescriptor) params.get("imageFile");
    
    byte[] bytes = null;
    if (imageFile != null) {
        try {
            bytes = fileStorageService.loadFile(imageFile);
        } catch (FileStorageException e) {
            showNotification("Unable to load image file", NotificationType.HUMANIZED);
        }
    }
    if (bytes != null) {
        embedded.setSource(imageFile.getName(), new ByteArrayInputStream(bytes));
        embedded.setType(Embedded.Type.IMAGE);
    } else {
        embedded.setVisible(false);
    }
    }

Веб-клиент позволяет выводить изображения из произвольных файлов на диске, доступных блоку Web Client. Для этого нужно определить каталог ресурсных файлов в свойстве приложения cuba.web.resourcesRoot, и указать для компонента Embedded имя файла внутри этого каталога:

embedded.setSource("my-logo.png");

Для встраивания в экран веб-клиента внешней веб-страницы необходимо передать компоненту URL:

try {
embedded.setSource(new URL("http://www.cuba-platform.com"));
} catch (MalformedURLException e) {
throw new RuntimeException(e);
}

Атрибуты embedded:

align id  
height visible  
width   
4.5.2.1.6. FieldGroup

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

XML-имя компонента: fieldGroup

Компонент реализован для блоков Web Client и Desktop Client.

Пример описания группы полей в XML-дескрипторе экрана:

<dsContext>
    <datasource id="orderDs"
                class="com.sample.sales.entity.Order"
                view="orderWithCustomer">
    </datasource>
</dsContext>
<layout>
    <fieldGroup id="orderFieldGroup" datasource="orderDs" width="250px">
        <field id="date"/>
        <field id="customer"/>
        <field id="amount"/>
    </fieldGroup>

Здесь в элементе dsContext определен источник данных datasource, который содержит один экземпляр сущности Order. Для компонента fieldGroup в атрибуте datasource указывается используемый источник данных, а в элементах field - какие атрибуты сущности, содержащейся в источнике данных, необходимо отобразить.

Элементы fieldGroup:

  • column - необязательный элемент, позволяющий располагать поля в несколько колонок. Для этого элементы field должны находиться не непосредственно внутри fieldGroup, а внутри своего column. Например:

    <fieldGroup id="orderFieldGroup" datasource="orderDs" width="100%">
        <column width="250px">
            <field id="num"/>
            <field id="date"/>
            <field id="amount"/>
        </column>
        <column width="400px">
            <field id="customer"/>
            <field id="info"/>
        </column>
    </fieldGroup>

    В данном случае поля будут расположены в две колонки, причем в первой колонке все поля будут шириной 250px, а во второй - 400px.

    Элемент column может иметь следующие атрибуты:

    • width - задает ширину полей данной колонки. По умолчанию ширина полей - 200px. В данном атрибуте ширина может быть задана как в пикселах, так и в процентах от общего размера колонки по горизонтали.

    • flex - число, задающее степень изменения общего размера данной колонки по горизонтали относительно других колонок при изменении ширины всего компонента fieldGroup. Например, можно задать одной колонке flex=1 а другой flex=3.

    • id - необязательный идентификатор колонки, позволяющий ссылаться на нее в случае расширении экрана.

  • field - основной элемент компонента, описывает одно поле компонента.

    Атрибуты элемента field:

    • id - обязательный атрибут, должен содержать либо название атрибута сущности, выводимого в поле, либо произвольный уникальный идентификатор программно определяемого поля. В последнем случае элемент field должен иметь также атрибут custom="true" (см. далее).

    • caption − позволяет задать заголовок поля. Если не задан, будет отображено локализованное название атрибута сущности.

    • visible − позволяет скрыть поле вместе с заголовком.

    • datasource − позволяет задать для данного поля источник данных, отличный от заданного для всего компонента fieldGroup. Таким образом в группе полей могут отображаться атрибуты разных сущностей.

    • optionsDatasource − задает имя источника данных, используемого для формирования списка опций. Данный атрибут можно задать для поля, связанного со ссылочным атрибутом сущности. По умолчанию выбор связанной сущности производится через экран выбора, а если optionsDatasource указан, то связанную сущность можно выбирать из выпадающего списка опций. Фактически указание optionsDatasource приводит к тому, что вместо компонента PickerField в поле используется LookupPickerField.

    • width − позволяет задать ширину поля без учета заголовка. По умолчанию ширина поля - 200px. Ширина может быть задана как в пикселах, так и в процентах от общего размера колонки по горизонтали. Для указания ширины всех полей одновременно можно использовать атрибут width элемента column, описанный выше.

    • custom - установка этого атрибута в true позволяет задать собственное представление поля, или говорит о том, что идентификатор поля не ссылается на атрибут сущности, и компонент, находящийся в поле, будет задан программно с помощью метода addCustomField() компонента FieldGroup (см. ниже).

    • link - установка атрибута в true позволяет отобразить вместо поля выбора сущности ссылку на экран просмотра экземпляра сущности (поддерживается только для Web Client). Такое поведение может быть необходимо, если требуется дать пользователю возможность просматривать связанную сущность, но саму связь он менять не должен.

    • linkScreen - позволяет указать идентификатор экрана, который будет открыт по нажатию на ссылку, включенную свойством link.

    • linkScreenOpenType - задает режим открытия экрана редактирования (THIS_TAB, NEW_TAB или DIALOG).

    • linkInvoke - позволяет заменить открытие окна на вызов метода контроллера.

    Следующие атрибуты элемента field можно применять в зависимости от типа атрибута сущности, отображаемого полем:

    • Если для текстового атрибута сущности задать значение атрибута mask, то в поле вместо компонента TextField будет использоваться компонент MaskedField с соотвествующей маской. В этом случае можно также задать атрибут valueMode.

    • Если для текстового атрибута сущности задать значение атрибута rows, то в поле вместо компонента TextField будет использоваться компонент TextArea с соответствующим количеством строк. В этом случае можно также задать атрибут cols.

    • Для текстового атрибута сущности можно задать атрибут maxLength аналогично описанному для TextField.

    • Для атрибута сущности типа date или dateTime можно задать атрибуты dateFormat и resolution для параметризации находящегося в поле компонента DateField.

    • Для атрибута сущности типа time можно задать атрибут showSeconds для параметризации находящегося в поле компонента TimeField.

Атрибуты fieldGroup:

  • Атрибут border может принимать значение hidden или visible. По умолчанию - hidden. При установке в значение visible компонент fieldGroup выделяется рамкой. В веб-реализации компонента отображение рамки осуществляется добавлением CSS-класса cuba-fieldgroup-border.

Методы интерфейса FieldGroup:

  • Метод addCustomField() используется вместе с атрибутом custom="true" элемента field и позволяет задать собственное представление поля. Он принимает два параметра: идентификатор поля, заданный в атрибуте id элемента field, и реализацию интерфейса FieldGroup.CustomFieldGenerator.

    Метод generateField() интерфейса CustomFieldGenerator вызывается компонентом FieldGroup, и в него передается источник данных и идентификатор поля, для которого зарегистрирован данный генератор. Метод должен вернуть визуальный компонент (или контейнер), который и будет отображен в поле.

    Пример использования:

    @Inject
    protected FieldGroup fieldGroup;
    @Inject
    protected ComponentsFactory componentsFactory;
    
    @Override
    public void init(Map<String, Object> params) {
        fieldGroup.addCustomField("password", new FieldGroup.CustomFieldGenerator() {
            @Override
            public Component generateField(Datasource datasource, String propertyId) {
                PasswordField passwordField = componentsFactory.createComponent(PasswordField.NAME);
                passwordField.setDatasource(datasource, propertyId);
                return passwordField;
            }
        });
    }

  • Метод getFieldComponent() возвращает визуальный компонент, находящийся в поле с указанным идентификатором. Это может потребоваться для дополнительной параметризации компонента, недоступной через атрибуты XML-элемента field, описанные выше.

    Вместо явного вызова getFieldComponent() для получения ссылки на компонент поля в контроллере экрана можно использовать инжекцию. Для этого следует использовать аннотацию @Named с указанием идентификатора самого fieldGroup, и через точку - идентификатора поля.

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

    <fieldGroup id="orderFieldGroup" datasource="orderDs">
        <field id="date"/>
        <field id="customer"/>
        <field id="amount"/>
    </fieldGroup>

    @Named("orderFieldGroup.customer")
    protected PickerField customerField;
    
    @Override
    public void init(Map<String, Object> params) {
        customerField.addOpenAction();
        customerField.removeAction(customerField.getAction(PickerField.ClearAction.NAME));
    }

    Для использования метода getFieldComponent() или инжекции компонентов полей необходимо знать тип компонента, находящегося в поле. В следующей таблице приведено соответствие типов атрибутов сущностей и создаваемых для них компонентов:

    Тип атрибута сущностиДополнительные условияТип компонента поля
    Связанная сущностьЗадан атрибут optionsDatasource LookupPickerField
      PickerField
    Перечисление (enum)  LookupField
    string Задан атрибут mask MaskedField
    Задан атрибут rows TextArea
      TextField
    boolean   CheckBox
    date, dateTime  DateField
    time   TimeField
    int, long, double, decimal  TextField

Все атрибуты fieldGroup:

Все атрибуты field:

Элементы field:

Атрибуты column:

4.5.2.1.7. FileMultiUploadField

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

XML-имя компонента: multiUpload.

Компонент реализован для блоков Web Client и Desktop Client. Для работы веб-версии компонента необходима поддержка браузером технологии Flash.

Рассмотрим пример использования компонента.

  • Объявляем компонент в XML-дескрипторе экрана:

    <multiUpload id="multiUploadField" caption="msg://upload"/>
  • В контроллере экрана инжектируем сам компонент, а также интерфейсы FileUploadingAPI и DataSupplier. Затем в методе init() добавляем компоненту слушатель, который будет реагировать на события успешной загрузки или ошибки:

    @Inject
    protected FileMultiUploadField multiUploadField;
    
    @Inject
    protected FileUploadingAPI fileUploading;
    
    @Inject
    protected DataSupplier dataSupplier;
    
    @Override
    public void init(Map<String, Object> params) {
    multiUploadField.addListener(new FileMultiUploadField.UploadListener() {
        @Override
        public void queueUploadComplete() {
            Map<UUID, String> uploadMap = multiUploadField.getUploadsMap();
            for (Map.Entry<UUID, String> entry : uploadMap.entrySet()) {
                UUID fileId = entry.getKey();
                String fileName = entry.getValue();
                FileDescriptor fd = fileUploading.getFileDescriptor(fileId, fileName);
                // save file to FileStorage
                try {
                    fileUploading.putFileIntoStorage(fileId, fd);
                } catch (FileStorageException e) {
                    new RuntimeException(e);
                }
                // save file descriptor to database
                dataSupplier.commit(fd, null);
            }
            multiUploadField.clearUploads();
        }
    });
    }

    Метод queueUploadComplete() будет вызван компонентом после успешной загрузки всех выбранных файлов во временное хранилище клиентского уровня. В этот момент вызовом метода getUploadsMap() у компонента можно получить мэп идентификаторов файлов во временном хранилище на имена файлов. Далее по этим данным для каждого файла создается соответствующий объект FileDescriptor. Объект com.haulmont.cuba.core.entity.FileDescriptor (не путать с java.io.FileDescriptor) является персистентной сущностью, которая однозначно идентифицирует загруженный файл и впоследствии используется для выгрузки файла из системы.

    Метод FileUploadingAPI.putFileIntoStorage() используется для перемещения загружаемого файла из временного хранилища клиентского уровня в FileStorage. Параметрами этого метода являются идентификатор файла во временном хранилище и объект FileDescriptor.

    После загрузки файла в FileStorage выполняется сохранение экземпляра FileDescriptor в базе данных посредством вызова DataSupplier.commit(). Возвращаемый этим методом сохраненный экземпляр может быть установлен в атрибут какой-либо сущности предметной области, связанной с данным файлом. В данном же случае FileDescriptor просто хранится в системе и дает доступ к файлу через экран Administration > External Files.

    После обработки файлов необходимо очистить список файлов вызовом clearUploads() на случай повторной загрузки.

  • Максимальный размер загружаемого файла определяется свойством приложения cuba.client.maxUploadSizeMb и по умолчанию равен 20Мб. При выборе пользователем файла большего размера выдается соответствующее сообщение и загрузка прерывается.

Атрибуты multiUpload:

4.5.2.1.8. FileUploadField

Компонент FileUploadField позволяет пользователю загружать файлы на сервер. Компонент представляет собой кнопку, при нажатии на которую на экране отображается стандартное для операционной системы окно, в котором можно выбрать один файл. Чтобы дать пользователю возможность загружать сразу несколько файлов, используйте компонент FileMultiUploadField.

XML-имя компонента: upload.

Компонент реализован для блоков Web Client и Desktop Client.

Рассмотрим пример использования компонента.

  • Объявляем компонент в XML-дескрипторе экрана:

    <upload id="uploadField" caption="msg://upload"/>
  • В контроллере экрана инжектируем сам компонент, а также интерфейсы FileUploadingAPI и DataSupplier. Затем в методе init() добавляем компоненту слушатель, который будет реагировать на события успешной загрузки или ошибки:

    @Inject
    protected FileUploadField uploadField;
    
    @Inject
    protected FileUploadingAPI fileUploading;
    
    @Inject
    protected DataSupplier dataSupplier;
    
    @Override
    public void init(Map<String, Object> params) {
    uploadField.addListener(new FileUploadField.ListenerAdapter() {
        @Override
        public void uploadSucceeded(Event event) {
            FileDescriptor fd = uploadField.getFileDescriptor();
            try {
                // save file to FileStorage
                fileUploading.putFileIntoStorage(uploadField.getFileId(), fd);
            } catch (FileStorageException e) {
                throw new RuntimeException(e);
            }
            // save file descriptor to database
            dataSupplier.commit(fd, null);
    
            showNotification("File uploaded: " + uploadField.getFileName(), NotificationType.HUMANIZED);
        }
    
        @Override
        public void uploadFailed(Event event) {
            showNotification("File upload error", NotificationType.HUMANIZED);
        }
    });
    }

    Метод uploadSucceeded() будет вызван компонентом после успешной загрузки файла во временное хранилище клиентского уровня. В этот момент у компонента можно получить объект FileDescriptor, соответствующий загруженному файлу. Объект com.haulmont.cuba.core.entity.FileDescriptor (не путать с java.io.FileDescriptor) является персистентной сущностью, которая однозначно идентифицирует загруженный файл и впоследствии используется для выгрузки файла из системы.

    Метод FileUploadingAPI.putFileIntoStorage() используется для перемещения загружаемого файла из временного хранилища клиентского уровня в FileStorage. Параметрами этого метода являются идентификатор файла во временном хранилище и объект FileDescriptor. Оба эти параметра предоставляет FileUploadField.

    После загрузки файла в FileStorage выполняется сохранение экземпляра FileDescriptor в базе данных посредством вызова DataSupplier.commit(). Возвращаемый этим методом сохраненный экземпляр может быть установлен в атрибут какой-либо сущности предметной области, связанной с данным файлом. В данном же случае FileDescriptor просто хранится в системе и дает доступ к файлу через экран Administration > External Files.

    Метод uploadFailed() вызывается компонентом FileUploadField в случае ошибки загрузки файла во временное хранилище клиентского уровня.

  • Максимальный размер загружаемого файла определяется свойством приложения cuba.client.maxUploadSizeMb и по умолчанию равен 20Мб. При выборе пользователем файла большего размера выдается соответствующее сообщение и загрузка прерывается.

Атрибуты upload:

4.5.2.1.9. Filter

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

Filter должен быть связан с источником данных collectionDatasource содержащим запрос на JPQL. Принцип действия фильтра основан на модификации этого запроса в соответствии с критериями, заданными пользователем. Таким образом фильтрация осуществляется на уровне БД при выполнении транслированного из JPQL в SQL запроса, и на Middleware и клиентский уровень загружаются только отобранные данные.

4.5.2.1.9.1. Использование фильтра

Типичный фильтр выглядит следующим образом:

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

Для того чтобы создать быстрый фильтр, нажмите на ссылку Add search condition (Добавить условие поиска). Отобразится экран выбора условий:

Рассмотрим возможные типы условий:

  • Properties (Атрибуты) – атрибуты данной сущности и связанных с ней сущностей. Отображаются персистентные атрибуты, явно заданные в элементе property XML-описателя фильтра, либо соответствующие правилам, указанным в элементе properties (см. ниже).

  • Custom conditions (Специальные условия) – условия, заданные разработчиком в элементах custom XML-описателя фильтра.

  • Create new (Создать новое) – позволяет создать новое произвольное условие на JPQL. Данный пункт доступен пользователю, если у него есть специфическое разрешение cuba.gui.filter.customConditions.

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

Быстрый фильтр можно сохранить для повторного использования в дальнейшем. Для этого нажмите на кнопку настроек фильтра и выберите Save/Save as (Сохранить/Сохранить как). Во всплывающем окне задайте имя нового фильтра:

Фильтр будет сохранен в выпадающем меню кнопки Search (Поиск).

Пункт меню Reset filter (Сбросить фильтр) позволяет сбросить все текущие условия поиска.

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

  • Save (Сохранить) – сохранить изменения в текущем фильтре.

  • Save as (Сохранить как) – сохранить фильтр под новым именем.

  • Edit (Редактировать) – открыть редактор фильтра (см. ниже).

  • Make default (Установить по умолчанию) – установить фильтр по умолчанию для данного экрана. Фильтр будет автоматически выводиться на панель при каждом открытии экрана.

  • Remove (Удалить) – удалить текущий фильтр.

  • Pin applied (Закрепить) – использовать результаты последнего поиска для последовательной фильтрации данных (см. Раздел 4.5.2.1.9.5, «Последовательное наложение фильтров»).

  • Save as search folder (Сохранить как папку поиска) – создать папку поиска на основе текущего фильтра.

  • Save as application folder (Сохранить как папку приложения) – создать папку приложения на основе текущего фильтра. Эта опция доступна только пользователям со специфическим разрешением cuba.gui.appFolder.global.

Опция Edit открывает редактор фильтра, который дает возможность расширенной настройки текущего фильтра:

Название фильтра указывается в поле Filter name (Имя фильтра). Это имя будет отображаться в списке доступных фильтров для текущего экрана.

Фильтр можно сделать global (то есть доступным для всех пользователей) с помощью установки флажка Available for all users (Общий) для всех пользователей, или установить текущий фильтр в качестве фильтра по умолчанию с помощью установки флажка Default (По умолчанию).

В дереве содержатся условия фильтра. Условия можно добавлять с помощью кнопки Add (Добавить) менять местами при помощи кнопок / или удалять с помощью кнопки Remove (Удалить).

Группировку условий по И или ИЛИ можно добавить с помощью соответствующих кнопок. Все добавленные на верхний уровень (то есть без явной группировки) условия объединяются по И.

При выборе условия в дереве в правой части редактора открывается список его свойств.

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

Свойство Width позволяет задать ширину поля ввода параметра для текущего условия. По умолчанию, условия на панели фильтров отображаются в три колонки. Ширина поля равняется количеству колонок, которое оно может занять (1, 2 или 3).

Значение параметра текущего условия по умолчанию можно задать в поле Default value (Значение по умолчанию).

Специальный заголовок условия фильтрации можно задать в поле Caption (Заголовок).

Поле Operation позволяет выбрать оператор поиска. Список доступных операторов зависит от типа атрибута.

При нажатии ОК в редакторе фильтра изменения сохраняются только для текущего быстрого поиска. Для того чтобы сохранить их для повторного использования в дальнейшем, нажмите на кнопку настройки фильтра и выберите Сохранить/Сохранить как. Иначе при закрытии экрана просмотра экземпляров сущности все изменения будут утеряны.

4.5.2.1.9.2. Описание компонента Filter

XML-имя компонента: filter.

Компонент реализован для блоков Web Client и Desktop Client.

Пример объявления компонента в XML-дескрипторе экрана:

<dsContext>
    <collectionDatasource id="carsDs" class="com.company.sample.entity.Car" view="carBrowse">
        <query>
            select c from ref$Car c order by c.createTs
        </query>
    </collectionDatasource>
</dsContext>
<layout>
    <filter id="carsFilter" datasource="carsDs">
        <properties include=".*"/>
    </filter>
    <table id="carsTable" width="100%">
        <columns>
            <column id="vin"/>
            <column id="model.name"/>
            <column id="colour.name"/>
        </columns>
        <rows datasource="carsDs"/>
    </table>
</layout>

Здесь в элементе dsContext определен источник данных collectionDatasource, который выбирает экземпляры сущности Car с помощью JPQL запроса. Для компонента filter в его атрибуте datasource указан фильтруемый источник данных. Данные отображаются компонентом Table, связанным с этим же источником.

Элемент filter может содержать вложенные элементы. Все они описывают условия, доступные пользователю для выбора в диалоге добавления условий:

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

    • include - обязательный атрибут, содержит регулярное выражение, которому должно соответствовать имя атрибута сущности.

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

    Например:

    <filter id="transactionsFilter" datasource="transactionsDs">
        <properties include=".*" exclude="(masterTransaction)|(authCode)"/>
    </filter>

    При использовании элемента properties автоматически игнорируются следующие атрибуты сущности:

  • property - явно включает атрибут сущности по имени. Данный элемент может иметь следующие атрибуты:

    • name - обязательный атрибут, содержит имя включаемого атрибута сущности. Может быть путем (через ".") по графу сущностей. Например:

      <filter id="transactionsFilter" datasource="transactionDs" applyTo="table">
          <properties include=".*" exclude="(masterTransaction)|(authCode)"/>
          <property name="creditCard.maskedPan" caption="msg://EmbeddedCreditCard.maskedPan"/>
          <property name="creditCard.startDate" caption="msg://EmbeddedCreditCard.startDate"/>
      </filter>

    • caption - локализованное название атрибута сущности для отображения условия фильтра. Как правило, представляет из себя строку с префиксом msg:// по правилам MessageTools.loadString().

      Если в атрибуте name указан путь (через ".") по графу сущностей, то атрибут caption является обязательным.

    • paramWhere − задает выражение на JPQL для отбора списка значений параметра условия, если параметр является связанной сущностью. Вместо алиаса сущности параметра в выражении нужно использовать метку (placeholder) {E}.

      Например, предположим, что сущность Car имеет ссылку на сущность Model. Тогда список возможных значений параметра может быть ограничен только моделями Audi:

      <filter id="carsFilter" datasource="carsDs">
          <property name="model" paramWhere="{E}.manufacturer = 'Audi'"/>
      </filter>

      В выражении JPQL можно использовать параметры экрана, атрибуты сессии, а также компоненты экрана, в том числе отображающие другие параметры. Правила задания параметров запроса описаны в Раздел 4.5.3.2, «Запросы в CollectionDatasourceImpl».

      Пример использования параметра сессии и параметра экрана:

      {E}.createdBy = :session$userLogin and {E}.name like :param$groupName

      Используя paramWhere можно вводить зависимости между параметрами. Например, предположим, что Manufacturer является отдельной сущностью. То есть Car ссылается на Model, которая в свою очередь ссылается на Manufacturer. Тогда для фильтра по Car можно создать два условия: первое для выбора Manufacturer и второе для выбора Model. Чтобы ограничить список моделей выбранным перед этим производителем, добавьте в выражение paramWhere параметр:

      {E}.manufacturer.id = :component$filter.model_manufacturer90062

      Здесь параметр ссылается на компонент, отображающий параметр Manufacturer. Имя компонента, отображающего параметр условия, можно узнать, вызвав контекстное меню на строке таблицы условий в редакторе фильтра:

    • paramView − задает представление, с которым будет загружаться список значений параметра условия, если параметр является связанной сущностью. Например, _local. Если не указано, используется _minimal.

  • custom - элемент, определяющий произвольное условие. Содержимым элемента должно быть выражение на JPQL (возможно использование JPQL Macros), которое будет добавлено в условие where запроса источника данных. Вместо алиаса отбираемой сущности в выражении нужно использовать метку (placeholder) {E}. Параметр условия может быть только один, и если он есть, обозначается символом ?.

    Пример фильтра с произвольными условиями:

    <filter id="carsFilter" datasource="carsDs">
        <properties include=".*"/>
        <custom name="vin" paramClass="java.lang.String" caption="msg://vin">
          {E}.vin like ?
        </custom>
        <custom name="colour" paramClass="com.company.sample.entity.Colour" caption="msg://colour"
                inExpr="true">
          ({E}.colour.id in (?))
        </custom>
        <custom name="repair" paramClass="java.lang.String" caption="msg://repair"
                join="join {E}.repairs cr">
          cr.description like ?
        </custom>
        <custom name="updateTs" caption="msg://updateTs">
          @between({E}.updateTs, now-1, now+1, day)
        </custom>
    </filter>

    Созданные custom условия отображаются в секции Специальные условия диалога добавления условий:

    Атрибуты элемента custom:

    • name − обязательный атрибут - имя условия.

    • caption − обязательный атрибут - локализованное название условия. Как правило, представляет из себя строку с префиксом msg:// по правилам MessageTools.loadString().

    • paramClass − Java-класс параметра условия. Если параметр отсутствует, то данный атрибут не обязателен.

    • inExpr − должен быть установлен в true, если выражение JPQL содержит условие in (?). При этом пользователь будет иметь возможность ввести несколько значений параметра данного условия.

    • join − необязательный атрибут для задания строки, которая будет добавлена в секцию from запроса источника данных. Это может потребоваться для создания условия по атрибуту связанной коллекции. Значение данного атрибута должно включать в себя предложения join или left join.

      Например, предположим что сущность Car имеет атрибут repairs, который представляет собой коллекцию экземпляров связанной сущности Repair. Тогда для фильтрации Car по атрибуту description сущности Repair можно написать следующее условие:

      <filter id="carsFilter" datasource="carsDs">
          <custom name="repair"
                  caption="msg://repair"
                  paramClass="java.lang.String"
                  join="join {E}.repairs cr">
              cr.description like ?
          </custom>
      </filter>

      При использовании такого условия исходный запрос источника данных:

      select c from sample$Car c order by c.createTs

      будет трансформирован в следующий:

      select c from sample$Car c join c.repairs cr
      where (cr.description like ?)
      order by c.createTs
    • paramWhere − задает выражение на JPQL для отбора списка значений параметра условия, если параметр является связанной сущностью. См. описание одноименного атрибута элемента property.

    • paramView − задает представление, с которым будет загружаться список значений параметра условия, если параметр является связанной сущностью. Например, _local. Если не указано, используется _minimal.

Атрибуты filter:

  • editable - если значение этого атрибута равно false, то кнопка Фильтр скрывается.

  • required - если значение этого атрибута равно true, то в списке фильтров значение <без фильтрации> не отображается, и пользователь обязательно должен выбрать один из доступных фильтров. Если для экрана не установлен фильтр по умолчанию, то в списке выбора фильтра автоматически устанавливается первый созданный фильтр.

  • manualApplyRequired − определяет, в какой момент будет применяться фильтр. Если значение атрибута равно false, то сразу при открытии экрана будет применяться фильтр по умолчанию. Если фильтр по умолчанию отсутствует, то установка значения false для атрибута теряет смысл. Если значение атрибута равно true, то фильтр будет применяться только после нажатия на кнопку Применить.

    Данный атрибут имеет приоритет над свойством приложения cuba.gui.genericFilterManualApplyRequired.

  • useMaxResults − ограничивает размер страницы загружаемых в источник данных экземпляров сущности. По умолчанию true.

    Если значение этого атрибута равно false, то фильтр не будет отображать поле Показывать строк. Количество записей в источнике данных (и соответственно, показываемых таблицей) будет ограничено только параметром MaxFetchUI механизма статистики сущностей, по умолчанию - 10000.

    Если данный атрибут не указан, или равен true, то поле Показывать строк отображается, если у пользователя также есть специфическое разрешение cuba.gui.filter.maxResults. Если разрешение cuba.gui.filter.maxResults отсутствует, то фильтр будет принудительно отбирать только первые N строк без возможности пользователя отключить это или указать другое N. Число N определяется параметрами FetchUI, DefaultFetchUI, получаемыми из механизма статистики сущностей.

    На рисунке далее показан вид фильтра со значением атрибута useMaxResults="true", запретом специфического разрешения cuba.gui.filter.maxResults и параметром DefaultFetchUI=2

  • textMaxResults - позволяет использовать текстовое поле вместо выпадающего списка в качестве поля Показывать строк. По умолчанию false.

  • folderActionsEnabled − при указании значения false позволяет скрыть следующие действия с фильтром: Сохранить как папку поиска, Сохранить как папку приложения. По умолчанию значение атрибута равно true, действия Сохранить как папку поиска, Сохранить как папку приложения доступны.

  • applyTo − необязательный атрибут, содержит идентификатор компонента, с которым связан фильтр. Используется в случае, когда необходимо иметь доступ к представлениям связанного компонента-таблицы. Например, сохраняя фильтр как папку поиска или как папку приложения, можно указать, какое представление будет применятся при просмотре этой папки.

  • caption - позволяет задать заголовок панели фильтров.

  • columnsQty - задает количество колонок с условиями для конкретного фильтра. Значение по умолчанию - 3.

Все атрибуты filter:

Элементы filter:

Атрибуты элемента properties:

Атрибуты элемента property:

Атрибуты элемента custom:

4.5.2.1.9.3. Права пользователей
  • Для создания/изменения/удаления глобальных (доступных всем пользователям) фильтров пользователь должен иметь разрешение cuba.gui.filter.global.

  • Для создания/изменения custom условий пользователь должен иметь разрешение cuba.gui.filter.customConditions.

  • Чтобы иметь возможность изменять максимальное количество строк на странице таблицы с помощью флажка и поля Show first N rows пользователь должен иметь разрешение cuba.gui.filter.maxResults. См. также атрибут фильтра useMaxResults.

Информация о том, как настраивать специфические разрешения, приведена в руководстве Подсистема безопасности.

4.5.2.1.9.4. Внешние параметры для управления фильтрами

Общесистемные параметры

Следующие свойства приложения влияют на поведение фильтров:

Параметры вызова экрана

При вызове экрана можно указать, какой фильтр и с какими параметрами должен быть применен сразу после открытия экрана. Для этого фильтр должен быть заранее создан, сохранен в базе данных, и соответствующая запись в таблице SEC_FILTER должна иметь заполненное поле CODE.

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

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

Пример описателя пункта главного меню, устанавливающего в открываемом экране sample$Car.browse в компоненте carsFilter фильтр с кодом FilterByVIN, с подстановкой в параметр условия component$carsFilter.vin79216 значения TMA:

<item id="sample$Car.browse">
<param name="carsFilter" value="FilterByVIN"/>
<param name="component$carsFilter.vin79216" value="TMA"/>
</item>

Следует отметить, что фильтр с установленным полем CODE обладает особыми свойствами:

  • Его не могут редактировать пользователи.

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

4.5.2.1.9.5. Последовательное наложение фильтров

Последовательное наложение фильтров

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

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

  • Декомпозировать сложные фильтры.

  • Применять фильтры на записи, отобранные с помощью папок приложения или поиска.

Чтобы применить этот механизм в пользовательском интерфейсе, выберите и примените один из фильтров. Затем нажмите на кнопку настроек фильтра и выберите Pin applied (Закрепить). Фильтр закрепится в верхней части панели фильтров. Далее можно применить к выбранным записям другой фильтр. Так последовательно можно накладывать друг на друга любое количество фильтров. Также фильтры можно удалять последовательно с помощью кнопки

Механизм последовательного наложения фильтров основан на возможности DataManager выполнять последовательные запросы.

4.5.2.1.10. GroupTable

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

XML-имя компонента: groupTable.

Компонент реализован только для блока Web Client. В Desktop Client ведет себя как обычная таблица.

Для GroupTable в атрибуте datasource элемента rows должен быть указан groupDatasource. В противном случае группировка работать не будет.

Пример использования:

<dsContext>
<groupDatasource id="ordersDs" class="com.sample.sales.entity.Order"
                view="orderWithCustomer">
   <query>
       select o from sales$Order o order by o.date
   </query>
</groupDatasource>
</dsContext>
<layout>
<groupTable id="ordersTable" width="100%">
    <columns>
        <group>
            <column id="date"/>
        </group>
        <column id="customer.name"/>
        <column id="amount"/>
    </columns>
    <rows datasource="ordersDs"/>
</groupTable>

group − необязательный элемент, может в единственном экземпляре находиться внутри columns. Содержит набор элементов column, по которым будет выполняться первоначальная группировка при открытии экрана.

При включенном атрибуте aggregatable таблица отображает результаты агрегации по всем строкам в дополнительной строке вверху, а также результаты агрегации по группам. Отображение агрегации по всем строкам можно отключить, установив false в атрибуте showTotalAggregation.

В остальном функциональность GroupTable аналогична простой таблице Table.

Атрибуты groupTable:

Элементы groupTable:

Элементы columns:

Атрибуты column:

Элементы column:

Атрибуты rows:

4.5.2.1.11. Label

Надпись (Label) − текстовый компонент, отображающий статический текст либо значение атрибута сущности.

XML-имя компонента: label

Компонент Label реализован для блоков Web Client и Desktop Client.

Пример задания надписи с текстом, взятым из пакета локализованных сообщений:

<label value="msg://orders"/>

Атрибут value предназначен для задания текста надписи.

В веб клиенте текст, содержащийся в атрибуте value, будет разбит на несколько строк, если по длине он превысит значение атрибута width. Поэтому для отображения многострочной надписи, достаточно указать абсолютное значение атрибута width. Если текст надписи слишком длинный, а значение атрибута width не определено, то текст будет урезан.

<label
   value="Надпись, которая должна быть разбита на несколько строк"
   width="200px"/>

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

<label id="dynamicLabel"/>
@Inject
private Label dynamicLabel;

public void init(Map<String, Object> params) {
dynamicLabel.setValue("Some value");
}

Компонент Label может отображать значение атрибута сущности. Для этого используются атрибуты datasource и property. Например:

<dsContext>
<datasource id="customerDs" class="com.sample.sales.entity.Customer" view="_local"/>
</dsContext>
<layout>
...
<label datasource="customerDs" property="name"/>

В данном случае компонент отображает атрибут name сущности Customer, находящейся в источнике данных customerDs.

Атрибут htmlEnabled указывает, каким образом будет рассматриваться значение атрибута value: как html-код, при htmlEnabled="true", или как строка. Обратите внимание, что не все html-теги поддерживаются в десктоп-реализации экрана.

Атрибуты label:

Элементы label:

4.5.2.1.12. Link

Ссылка (Link) − компонент-гиперссылка, позволяющая открывать внешние веб-ресурсы единообразно для веб и десктоп клиента.

XML-имя компонента: link

Пример XML-описания компонента link:

<link caption="Link" url="https://www.cuba-platform.com" target="_blank"/>

Атрибуты link:

  • url - адрес ресурса.

  • target - для веб клиента задает способ открытия страницы, аналогичен атрибуту target HTML-тега <a>.

Другие атрибуты Link: align | caption | description | enable | id | icon | stylename | visible | width

4.5.2.1.13. LinkButton

Кнопка-ссылка (LinkButton) − кнопка, выглядящая как гиперссылка.

XML-имя компонента: linkButton

Компонент кнопки-ссылки реализован для блоков Web Client и Desktop Client.

Кнопка-ссылка может содержать текст или пиктограмму (или и то и другое). На рисунке ниже отражены разные виды кнопок.

Кнопка-ссылка отличается от обычной кнопки Button только своим внешним видом. Все свойства и поведение идентичны описанным для Button.

Пример XML-описания кнопки-ссылки, вызывающей метод someMethod() контроллера, с надписью (атрибут caption), всплывающей подсказкой (атрибут description) и пиктограммой (атрибут icon):

<linkButton id="linkButton"
        caption="msg://linkButton"
        description="Press me"
        icon="icons/save.png"
        invoke="someMethod"/>

Атрибуты linkButton:

4.5.2.1.14. LookupField

Компонент для выбора значения из выпадающего списка. Выпадающий список реализует фильтрацию значений по мере ввода пользователя и постраничный вывод доступных значений.

XML-имя компонента: lookupField.

Компонент LookupField реализован для блоков Web Client и Desktop Client.

  • Простейший вариант использования LookupField - выбор значения перечисления (enum) для атрибута сущности. Например, сущность Role имеет атрибут type типа RoleType, который является перечислением. Тогда для редактирования этого атрибута можно использовать LookupField следующим образом:

    <dsContext>
    <datasource id="roleDs" class="com.haulmont.cuba.security.entity.Role" view="_local"/>
    </dsContext>
    <layout>
    <lookupField datasource="roleDs" property="type"/>

    Как видно из примера, в экране описывается источник данных roleDs для сущности Role. В компоненте lookupField в атрибуте datasource указывается ссылка на источник данных, а в атрибуте property − название атрибута сущности, значение которого должно быть отображено. В данном случае атрибут является перечислением, и в выпадающем списке будут отображены локализованные названия всех значений этого перечисления.

  • Аналогично можно использовать LookupField для выбора экземпляра связанной сущности. Для формирования списка опций используется атрибут optionsDatasource:

    <dsContext>
    <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
    <collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
        <query>select c from sample$Colour c</query>
    </collectionDatasource>
    </dsContext>
    <layout>
    <lookupField datasource="carDs" property="colour" optionsDatasource="coloursDs"/>

    В данном случае компонент отобразит отобразит имена экземпляров сущности Colour, находящихся в источнике данных colorsDs, а выбранное значение подставится в атрибут colour сущности Car, находящейся в источнике данных carDs.

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

  • Список опций компонента может быть задан произвольно с помощью методов setOptionsList() и setOptionsMap(), либо с помощью XML-атрибута optionsDatasource.

    • Метод setOptionsList() позволяет программно задать список опций компонента. Для этого объявляем компонент в XML-дескрипторе:

      <lookupField id="numberOfSeatsField" datasource="modelDs" property="numberOfSeats"/>

      Затем инжектируем компонент в контроллер и в методе init() задаем ему список опций:

      @Inject
      protected LookupField numberOfSeatsField;
      
      @Override
      public void init(Map<String, Object> params) {
      List<Integer> list = new ArrayList<>();
      list.add(2);
      list.add(4);
      list.add(5);
      list.add(7);
      numberOfSeatsField.setOptionsList(list);
      }

      В выпадающем списке компонента отобразятся числа 2, 4, 5, 7. Выбранное число подставится в атрибут numberOfSeats сущности, находящейся в источнике данных modelDs.

    • Метод setOptionsMap() позволяет задать строковые названия и значения опций по отдельности. Например, для описанного в XML-дескрипторе компонента numberOfSeatsField в методе init() контроллера задаем мэп опций:

      @Inject
      protected LookupField numberOfSeatsField;
      
      @Override
      public void init(Map<String, Object> params) {
      Map<String, Object> map = new LinkedHashMap<>();
      map.put("two", 2);
      map.put("four", 4);
      map.put("five", 5);
      map.put("seven", 7);
      numberOfSeatsField.setOptionsMap(map);
      }

      В выпадающем списке компонента отобразятся строки two, four, five, seven. Однако значением компонента будет число, соответствующее выбранной строке. Оно и подставится в атрибут numberOfSeats сущности, находящейся в источнике данных modelDs.

  • С помощью атрибута filterMode можно задать тип фильтрации опций при вводе пользователя:

    • NO − нет фильтрации.

    • STARTS_WITH − по началу фразы.

    • CONTAINS − по любому вхождению (используется по умолчанию).

  • Если у компонента LookupField не установлен атрибут required, и если связанный атрибут сущности не объявлен как обязательный, то в списке опций компонента присутствует пустая строка, при выборе которой компонент возвращает значение null. Атрибут nullName позволяет задать строку, отображаемую в этом случае вместо пустой. Пример использования:

    <lookupField datasource="carDs" property="colour" optionsDatasource="coloursDs" nullName="(none)"/>

    В данном случае вместо пустой строки отобразится строка (none), при выборе которой в связанный атрибут сущности подставится значение null.

    При программном задании списка опций методом setOptionsList() можно одну из опций передать в метод setNullOption(). Тогда при ее выборе пользователем значением компонента будет null.

  • Компонент LookupField способен обрабатывать ввод пользователя при отсутствии подходящей опции в списке. Для этого используются методы setNewOptionAllowed() и setNewOptionHandler(). Например:

    @Inject
    protected LookupField colourField;
    
    @Inject
    protected CollectionDatasource<Colour, UUID> coloursDs;
    
    @Override
    public void init(Map<String, Object> params) {
    colourField.setNewOptionAllowed(true);
    colourField.setNewOptionHandler(new LookupField.NewOptionHandler() {
        @Override
        public void addNewOption(String caption) {
            Colour colour = new Colour();
            colour.setName(caption);
            coloursDs.addItem(colour);
            colourField.setValue(colour);
        }
    });
    }

    Обработчик NewOptionHandler вызывается, если пользователь ввел некоторое значение, не совпадающее ни с одной из опций, и нажал Enter. В данном случае в обработчике создается новый экземпляр сущности Colour, его атрибут name устанавливается в значение, введенное пользователем, этот экземпляр добавляется в источник данных опций и выбирается в компоненте.

    Вместо имплементации интерфейса LookupField.NewOptionHandler для обработки ввода пользователя можно использовать XML-атрибут newOptionHandler с указанным в нем методом контроллера. Данный метод должен иметь два параметра - первый типа LookupField, второй типа String. В них будут переданы соответственно экзампляр компонента и введенное пользователем значение.

Атрибуты lookupField:

align | caption | captionProperty | datasource | description | editable | enable | filterMode | height | id | inputPrompt | newOptionHandler | nullName | optionsDatasource | property | required | requiredMessage | stylename | visible | width

Элементы lookupField:

validator

4.5.2.1.15. LookupPickerField

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

XML-имя компонента: lookupPickerField.

Компонент реализован для блоков Web Client и Desktop Client.

LookupPickerField является по сути гибридом LookupField и PickerField, поэтому все описанное для этих интерфейсов верно и для него. Исключением является список действий по умолчанию, добавляемых при определении компонента в XML: для LookupPickerField это действия lookup и open .

Пример использования LookupPickerField для выбора значения ссылочного атрибута colour сущности Car:

<dsContext>
<datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
<collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
    <query>select c from sample$Colour c</query>
</collectionDatasource>
</dsContext>
<layout>
<lookupPickerField datasource="carDs" property="colour" optionsDatasource="coloursDs"/>

Атрибуты lookupPickerField:

align | caption | captionProperty | datasource | description | editable | enable | filterMode | height | id | inputPrompt | metaClass | nullName | optionsDatasource | property | required | requiredMessage | stylename | visible | width

Элементы lookupPickerField:

actions | validator

4.5.2.1.16. MaskedField

Текстовое поле, в которое данные вводятся в определенном формате. MaskedField удобно использовать, например, для ввода телефонных номеров.

XML-имя компонента: maskedField.

Компонент MaskedField реализован только для блока Web Client.

MaskedField в основном повторяет функциональность TextField, за исключением того, что ему нельзя установить datatype. То есть MaskedField предназначен для работы только с текстом и строковыми атрибутами сущностей. MaskedField имеет следующие специфические атрибуты:

  • mask - задает маску для поля. Чтобы задать маску, используются следующие символы:

    • # - цифра

    • U - буква верхнего регистра

    • L - буква нижнего регистра

    • ? - буква

    • А - буква или цифра

    • * - любой символ

    • H - hex символ в верхнем регистре

    • h - hex символ в нижнем регистре

    • ~ - знак + или -

  • valueMode - определяет формат возвращаемого значения (с маской, или без) и может принимать значение masked или clear.

Пример текстового поля с маской для ввода номеров телефонов:

<maskedField id="phoneNumberField" mask="(###)###-##-##" valueMode="masked"/>
<button caption="msg://showPhoneNumberBtn" invoke="showPhoneNumber"/>
@Inject
private MaskedField phoneNumberField;

public void showPhoneNumber(){
showNotification((String) phoneNumberField.getValue(), NotificationType.HUMANIZED);
}

Атрибуты maskedField:

Элементы maskedField:

4.5.2.1.17. OptionsGroup

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

XML-имя компонента: optionsGroup.

Компонент OptionsGroup реализован для блоков Web Client и Desktop Client.

  • Простейший вариант использования OptionsGroup - выбор значения перечисления (enum) для атрибута сущности. Например, сущность Role имеет атрибут type типа RoleType, который является перечислением. Тогда для редактирования этого атрибута можно использовать OptionsGroup следующим образом:

    <dsContext>
    <datasource id="roleDs" class="com.haulmont.cuba.security.entity.Role" view="_local"/>
    </dsContext>
    <layout>
    <optionsGroup datasource="roleDs" property="type"/>

    Как видно из примера, в экране описывается источник данных roleDs для сущности Role. В компоненте optionsGroup в атрибуте datasource указывается ссылка на источник данных, а в атрибуте property − название атрибута сущности, значение которого должно быть отображено.

    В результате компонент примет следующий вид:

  • Список опций компонента может быть задан произвольно с помощью методов setOptionsList() и setOptionsMap(), либо с помощью XML-атрибута optionsDatasource.

    • Метод setOptionsList() позволяет программно задать список опций компонента. Для этого объявляем компонент в XML-дескрипторе:

      <optionsGroup id="numberOfSeatsField"/>

      Затем инжектируем компонент в контроллер и в методе init() задаем ему список опций:

      @Inject
      protected OptionsGroup numberOfSeatsField;
      
      @Override
      public void init(Map<String, Object> params) {
      List<Integer> list = new ArrayList<>();
      list.add(2);
      list.add(4);
      list.add(5);
      list.add(7);
      numberOfSeatsField.setOptionsList(list);
      }

      Компонент примет следующий вид:

      При этом метод getValue() компонента в зависимости от выбранной опции будет возвращать Integer значения 2,4,5,7.

    • Метод setOptionsMap() позволяет задать строковые названия и значения опций по отдельности. Например, для описанного в XML-дескрипторе компонента numberOfSeatsField в методе init() контроллера задаем мэп опций:

      @Inject
      protected OptionsGroup numberOfSeatsField;
      
      @Override
      public void init(Map<String, Object> params) {
      Map<String, Object> map = new LinkedHashMap<>();
      map.put("two", 2);
      map.put("four", 4);
      map.put("five", 5);
      map.put("seven", 7);
      numberOfSeatsField.setOptionsMap(map);
      }

      Компонент примет следующий вид:

      При этом метод getValue() компонента в зависимости от выбранной опции будет возвращать Integer значения 2,4,5,7, а не строки, отображаемые на экране.

    • Компонент может брать список опций из источника данных. Для этого используется атрибут optionsDatasource. Например:

      <dsContext>
      <collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
          <query>select c from sample$Colour c</query>
      </collectionDatasource>
      </dsContext>
      <layout>
      <optionsGroup id="coloursField" optionsDatasource="coloursDs"/>

      В данном случае компонент coloursField отобразит имена экземпляров сущности Colour, находящихся в источнике данных coloursDs, а его метод getValue() вернет выбранный экземпляр сущности.

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

  • С помощью атрибута multiselect можно переключить OptionsGroup в режим множественного выбора. Если multiselect включен, то компонент отображается как группа независимых флажков, а значением компонента является список выбранных опций.

    Например, создадим в XML-дескрипторе экрана компонент:

    <optionsGroup id="roleTypesField" multiselect="true"/>

    И в контроллере зададим для него список опций - значения перечисления RoleType:

    @Inject
    protected OptionsGroup roleTypesField;
    
    @Override
    public void init(Map<String, Object> params) {
    roleTypesField.setOptionsList(Arrays.asList(RoleType.values()));
    }

    Компонент примет следующий вид:

    В данном случае метод getValue() компонента вернет объект типа java.util.List, содержащий значения RoleType.READONLY и RoleType.DENYING.

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

  • Атрибут orientation задает расположение элементов группы. По умолчанию элементы располагаются по вертикали. Значение horizontal задает горизонтальное расположение.

Атрибуты optionsGroup:

Элементы optionsGroup:

4.5.2.1.18. PasswordField

Текстовое поле, которое вместо символов, введенных пользователем, отображает эхо-символы.

XML-имя компонента: passwordField.

PasswordField реализован для блоков Web Client и Desktop Client.

PasswordField в основном аналогичен компоненту TextField, за исключением того, что ему нельзя установить datatype. То есть PasswordField предназначен для работы только с текстом и строковыми атрибутами сущностей.

Пример использования:

<passwordField id="passwordField" caption="msg://name"/>
<button caption="msg://buttonsName" invoke="showPassword"/>
@Inject
private PasswordField passwordField;

public void showPassword(){
showNotification((String) passwordField.getValue(), NotificationType.HUMANIZED);
}

Атрибуты passwordField:

Элементы passwordField:

4.5.2.1.19. PickerField

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

XML-имя компонента: pickerField.

Компонент PickerField реализован для блоков Web Client и Desktop Client.

  • Как правило, PickerField используется для работы со ссылочными атрибутами сущностей. При этом компоненту достаточно указать атрибуты datasource и property:

    <dsContext>
    <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
    </dsContext>
    <layout>
    <pickerField datasource="carDs" property="colour"/>

    Как видно из примера, в экране описывается источник данных carDs для некоторой сущности Car, имеющей атрибут colour. В элементе pickerField в атрибуте datasource указывается ссылка на источник данных, а в атрибуте property − название атрибута сущности, значение которого должно быть отображено в компоненте. Атрибут сущности должен являться ссылкой на другую сущность, в приведенном примере это Colour.

  • Для PickerField можно определить произвольное количество действий, отображаемых кнопками справа. Это можно сделать как в XML-дескрипторе с помощью вложенного элемента actions, так и программно в контроллере методом addAction().

    • Существуют стандартные действия, определенные перечислением PickerField.ActionType: lookup, clear, open. Они выполняют соответственно выбор связанной сущности, очистку поля и открытие экрана редактирования выбранной связанной сущности. Для стандартных действий в XML не нужно определять никаких атрибутов, кроме идентификатора. Если при объявлении компонента никаких действий в элементе actions не задано, загрузчик XML определит для него действия lookup и clear. Чтобы добавить к действиям по умолчанию, например, действие open, нужно определить элемент actions следующим образом:

      <pickerField datasource="carDs" property="colour"/>
      <actions>
          <action id="lookup"/>
          <action id="open"/>
          <action id="clear"/>
      </actions>
      </pickerField>

      Элемент action не дополняет, а переопределяет набор стандартных действий, поэтому необходимо указывать идентификаторы всех требуемых действий. Компонент примет следующий вид:

      Для программного задания стандартных действий служат методы addLookupAction(), addOpenAction() и addClearAction(). Если компонент определен в XML-дескрипторе без вложенного элемента actions, то достаточно добавить недостающие действия:

      @Inject
      protected PickerField colourField;
      
      @Override
      public void init(Map<String, Object> params) {
      colourField.addOpenAction();
      }    

      Если же компонент создается в контроллере, то никаких действий по умолчанию он не получает, и необходимо добавить все нужные действия явно:

      @Inject
      protected ComponentsFactory componentsFactory;
      
      @Override
      public void init(Map<String, Object> params) {
      PickerField colourField = componentsFactory.createComponent(PickerField.NAME);
      colourField.setDatasource(carDs, "colour");
      colourField.addLookupAction();
      colourField.addOpenAction();
      colourField.addClearAction();
      }

      Стандартные действия можно параметризовать. В XML-дескрипторе возможности для этого ограничены: существует только атрибут openType, в котором можно задать режим открытия экрана выбора (для LookupAction) или редактирования (для OpenAction).

      При программном создании действий можно задать любые свойства объектов PickerField.LookupAction, PickerField.OpenAction и PickerField.ClearAction, возвращаемых методами добавления стандартных действий. Например, так можно задать специфический экран выбора:

      PickerField.LookupAction lookupAction = customerField.addLookupAction();
      lookupAction.setLookupScreen("customerLookupScreen");

      Подробнее см. JavaDocs классов стандартных действий.

    • Произвольные действия в XML-дескрипторе также определяются во вложенном элементе actions, например:

      <pickerField datasource="carDs" property="colour"/>
      <actions>
          <action id="lookup"/>
          <action id="show" icon="icons/show.png"
                  invoke="showColour" caption=""/>
      </actions>
      </pickerField>

      Программно задать произвольное действие можно следующим образом:

      @Inject
      protected PickerField colourField;
      
      @Override
      public void init(Map<String, Object> params) {
      colourField.addAction(new AbstractAction("show") {
          @Override
          public void actionPerform(Component component) {
              showColour(colourField.getValue());
          }
          @Override
          public String getCaption() {
              return "";
          }
          @Override
          public String getIcon() {
              return "icons/show.png";
          }
      });
      }

      Декларативное и программное создание действий подробно описано в Раздел 4.5.4, «Действия. Интерфейс Action».

  • Компонент PickerField можно использовать без непосредственной привязки к данным, то есть без указания datasource и property. В этом случае для указания типа сущности, с которой должен работать PickerField, используется атрибут metaClass. В нем необходимо указать имя сущности в метаданных, например:

    <pickerField id="colourField" metaClass="sample$Colour"/>

    Экземпляр выбранной сущности можно получить, инжектировав компонент в контроллер и вызвав его метод getValue().

    Для правильной работы компонента PickerField необходима либо установка атрибута metaClass, либо одновременная установка атрибутов datasource и property.

  • В компоненте PickerField можно использовать горячие клавиши: см. Раздел 4.5.11, «Горячие клавиши».

Атрибуты pickerField:

Элементы pickerField:

4.5.2.1.20. PopupButton

Кнопка с выпадающим списком действий.

XML-имя компонента: popupButton.

Компонент реализован для блоков Web Client и Desktop Client.

Кнопка с выпадающим списком действий может содержать текст или пиктограмму (или и то и другое). На рисунке ниже отражены разные виды кнопок.

Пример кнопки с выпадающим списком, содержащим два действия:

<popupButton id="popupButton" caption="msg://popupButton" description="Press me">
<actions>
  <action id="popupAction1" caption="msg://action1" invoke="someAction1"/>
  <action id="popupAction2" caption="msg://action2" invoke="someAction2"/>
</actions>
</popupButton>

Кнопка имеет надпись, заданную с помощью атрибута caption, и всплывающую подсказку, определенную в атрибуте description. Выпадающий список действий задан в элемене actions. PopupButton отображает только следующие свойства действий: caption, enable, visible. Свойства description, icon, shortcut игнорируются.

Атрибуты popupButton:

Элементы popupButton:

4.5.2.1.21. ProgressBar

Компонент ProgressBar служит для отображения хода выполнения некоторого длительного процесса.

XML-имя компонента: progressBar

Компонент реализован для блоков Web Client и Desktop Client.

Пример использования компонента совместно с механизмом фоновых задач:

<progressBar id="progressBar" width="100%"/>
        

@Inject
protected ProgressBar progressBar;

@Inject
protected BackgroundWorker backgroundWorker;

private static final int ITERATIONS = 5;

@Override
public void init(Map<String, Object> params) {
BackgroundTask<Integer, Void> task = new BackgroundTask<Integer, Void>(300, this) {
    @Override
    public Void run(TaskLifeCycle<Integer> taskLifeCycle) throws Exception {
        for (int i = 1; i <= ITERATIONS; i++) {
            TimeUnit.SECONDS.sleep(2); // time consuming task
            taskLifeCycle.publish(i);
        }
        return null;
    }

    @Override
    public void progress(List<Integer> changes) {
        float lastValue = changes.get(changes.size() - 1);
        progressBar.setValue(lastValue / ITERATIONS);
    }
};

BackgroundTaskHandler taskHandler = backgroundWorker.handle(task);
taskHandler.execute();
}

Здесь в методе BackgroundTask.progress(), выполняемом в UI-потоке, компоненту ProgressBar устанавливается текущее значение. Значением компонента должно быть число типа float от 0.0 до 1.0.

Если выполняемый процесс не может передавать информацию о прогрессе, то с помощью атрибута indeterminate можно задать отображение неопределенного состояния индикатора. Если значение атрибута равно true, то индикатор отображает неопределенное состояние. По умолчанию false. Например:

<progressBar id="progressBar" width="100%" indeterminate="true"/>

Атрибуты progressBar:

4.5.2.1.22. Related Entities

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

XML-имя компонента: relatedEntities

Компонент реализован для блоков Web Client и Desktop Client.

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

По умолчанию для выбранного в списке класса сущности открывается браузер сущности, определенный по соглашениям (.browse, .lookup). Опционально, экран можно явно задать в компоненте.

В открытом браузере динамически создается фильтр, который выбирает связанные с выбранными сущностями записи.

Пример описания компонента в XML-дескрипторе экрана:

      <table id="invoiceTable"
             multiselect="true"
             width="100%">
          <actions>
              <action id="create"/>
              <action id="edit"/>
              <action id="remove"/>
          </actions>
          <buttonsPanel id="buttonsPanel">
              <button id="createBtn"
                      action="invoiceTable.create"/>
              <button id="editBtn"
                      action="invoiceTable.edit"/>
              <button id="removeBtn"
                      action="invoiceTable.remove"/>
              <relatedEntities for="invoiceTable"
                               openType=”NEW_TAB”>
              <property name="invoiceItems"
                        screen="sales$InvoiceItem.lookup"
                        filterCaption="msg://invoiceItems"/>
          </relatedEntities>
      </buttonsPanel>
      

Атрибут for является обязательным. В нем указывается идентификатор таблицы.

Атрибут openType=”NEW_TAB” устанавливает режим открытия браузера (новая вкладка). По умолчанию браузер открывается в текущей вкладке.

Элемент property позволяет явно задать связанную сущность, которая будет отображаться в выпадающем списке.

Атрибуты property:

  • name - имя атрибута текущей сущности, ссылающегося на связанную сущность

  • screen - идентификатор браузера, открывающегося при выборе сущности в списке

  • filterCaption - имя динамически формируемого фильтра

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

Рисунок 22. Компонент Related Entities в таблице

Компонент Related Entities в таблице

Рисунок 23. Браузер связанных сущностей в новой вкладке

Браузер связанных сущностей в новой вкладке

Все атрибуты relatedEntities:

Атрибуты property:

4.5.2.1.23. RichTextArea

Текстовая область для отображения и ввода форматированного текста.

XML-имя компонента: richTextArea

Компонент RichTextArea реализован только для блока Web Client.

RichTextArea в основном повторяет функциональность TextField , за исключением того, что ему нельзя установить datatype. То есть RichTextArea предназначен для работы только с текстом и строковыми атрибутами сущностей.

К тексту, вводимому в компоненте RichTextArea, можно применять средства для форматирования: изменять начертание шрифта, его размер, гарнитуру − с помощью элементов управления, расположенных в верхней части компонента.

Атрибуты richTextArea:

4.5.2.1.24. SearchPickerField

Компонент SearchPickerField служит для поиска экземпляров сущностей по вводимой пользователем строке. Пользователю достаточно ввести несколько символов и нажать клавишу Enter. Если поиск дал несколько совпадений, найденные значения отображаются в виде выпадающего списка. Если же критерию поиска соответствует только один экземпляр, он сразу становится значением компонента. SearchPickerField позволяет также выполнять действия нажатием на кнопки справа.

XML-имя компонента: searchPickerField.

Компонент реализован для блоков Web Client и Desktop Client.

  • Для работы компонента SearchPickerField необходимо создать collectionDatasource, и задать в нем запрос, содержащий условия поиска. Условие обязательно должно содержать параметр с именем custom$searchString - именно в него компонент передает введенную пользователем подстроку при нажатии Enter. Источник данных с условием поиска должен быть указан в атрибуте optionsDatasource компонента. Например:

    <dsContext>
    <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
    <collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
        <query>
            select c from sample$Colour c
            where c.name like :(?i)custom$searchString
        </query>
    </collectionDatasource>
    </dsContext>
    <layout>
    <searchPickerField datasource="carDs" property="colour" optionsDatasource="coloursDs"/>

    В данном случае компонент будет искать экземпляры сущности Colour по вхождению подстроки в ее атрибут name. Префикс (?i) служит для регистро-независимого поиска (см. Раздел 4.5.3.2.4, «Поиск подстроки без учета регистра»). Выбранное значение подставится в атрибут colour сущности Car, находящейся в источнике данных carDs.

  • С помощью атрибута minSearchStringLength можно задать минимальное количество символов, которое должен ввести пользователь для поиска значения.

  • В контроллере экрана для компонента можно реализовать методы, вызываемые в двух случаях:

    • если количество введенных символов меньше значения атрибута minSearchStringLength.

    • если поиск введенных пользователем символов не дал результатов.

    Пример реализации методов для вывода на экран сообщений:

    @Inject
    private SearchPickerField colourField;
    
    @Override
    public void init(Map<String, Object> params) {
    colourField.setSearchNotifications(new SearchField.SearchNotifications() {
        @Override
        public void notFoundSuggestions(String filterString) {
            showNotification("No colours found for search string: " + filterString,
                NotificationType.TRAY);
        }
    
        @Override
        public void needMinSearchStringLength(String filterString, int minSearchStringLength) {
            showNotification("Minimum length of search string is " + minSearchStringLength,
                NotificationType.TRAY);
        }
    });
    }
  • SearchPickerField реализует интерфейсы LookupField и PickerField, поэтому все описанное для этих интерфейсов в части работы с сущностями верно и для него. Исключением является список действий по умолчанию, добавляемых при определении компонента в XML: для SearchPickerField это действия lookup и open .

Атрибуты searchPickerField:

align | caption | captionProperty | datasource | description | editable | enable | filterMode | height | id | inputPrompt | metaClass | minSearchStringLength | nullName | optionsDatasource | property | required | requiredMessage | stylename | visible | width

Элементы searchPickerField:

actions | validator

4.5.2.1.25. Table

Компонент Table позволяет выводить информацию в табличном виде, сортировать данные, управлять колонками и заголовками таблицы, вызывать действия для выбранных строк.

XML-имя компонента: table

Компонент реализован для блоков Web Client и Desktop Client.

Пример описания таблицы в XML-дескрипторе экрана:

<dsContext>
    <collectionDatasource id="ordersDs"
                          class="com.sample.sales.entity.Order"
                          view="orderWithCustomer">
        <query>
            select o from sales$Order o order by o.date
        </query>
    </collectionDatasource>
</dsContext>
<layout>
    <table id="ordersTable" width="300px">
        <columns>
            <column id="date"/>
            <column id="customer.name"/>
            <column id="amount"/>
        </columns>
        <rows datasource="ordersDs"/>
    </table>

Здесь в элементе dsContext определен источник данных collectionDatasource, который выбирает сущности Order с помощью JPQL запроса

select o from sales$Order o order by o.date. Для компонента table в элементе rows указывается используемый источник данных, а в элементе columns - какие атрибуты сущности, содержащейся в источнике данных, использовать в качестве колонок.

Элементы table:

  • rows - обязательный элемент, в атрибуте datasource которого необходимо объявить используемый таблицей источник данных.

    Для строк можно настроить отображение заголовков - задать каждой строке свой значок в дополнительной колонке слева. Для этого в контроллере экрана необходимо реализовать интерфейс Table.IconProvider и установить его таблице:

    @Inject
    protected Table customersTable;
    ...
        customersTable.setIconProvider(new Table.IconProvider() {
            @Nullable
            @Override
            public String getItemIcon(Entity entity) {
                CustomerGrade grade = ((Customer) entity).getGrade();
                switch (grade) {
                    case PREMIUM: return "icons/premium_grade.png";
                    case HIGH: return "icons/high_grade.png";
                    case MEDIUM: return "icons/medium_grade.png";
                    default: return null;
                }
            }
        });

  • columns - обязательный элемент, определяет набор колонок таблицы.

    Каждая колонка описывается во вложенном элементе column со следующими атрибутами:

    • id − обязательный атрибут, содержит название атрибута сущности, выводимого в колонке. Может быть как непосредственным атрибутом сущности, находящейся в источнике данных, так и атрибутом связанной сущности - переход по графу объектов обозначается точкой. Например:

      <columns>
          <column id="date"/>
          <column id="customer"/>
          <column id="customer.name"/>
          <column id="customer.address.country"/>
      </columns>

    • caption − необязательный атрибут, содержит заголовок колонки. Если не задан, будет отображено локализованное название атрибута сущности.

    • collapsed − необязательный атрибут, при указании true колонка будет изначально скрыта. Пользователь может управлять отображением колонок с помощью меню, доступного по кнопке в правой верхней части таблицы, если атрибут columnControlVisible таблицы не false. По умолчанию collapsed имеет значение false.

    • width − необязательный атрибут, отвечает за изначальную ширину колонки.

    • align - необязательный атрибут, устанавливает выравнивание текста в ячейках данной колонки. Возможные значения: LEFT, RIGHT, CENTER. По умолчанию LEFT.

    • editable − необязательный атрибут, разрешает/запрещает редактирование данной колонки в редактируемой таблице. Чтобы колонка была редактируемой, атрибут editable всей таблицы (см. ниже) также должен быть установлен в true.

    • maxTextLength - необязательный атрибут, позволяет ограничивать количество символов в ячейке. При этом если разница между фактическим и допустимым количеством символов не превышает порог в 10 символов, "лишние" символы не скрываются. Для просмотра полной записи надо кликнуть на ее видимую часть. Пример колонки с ограничением в 5 символов:

    • link - установка атрибута в true позволяет отобразить в ячейке таблицы ссылку на экран просмотра экземпляра сущности (поддерживается только для Web Client). Атрибут link="true") может указываться и для колонок примитивных типов: в этом случае, при нажатии на ссылку будет открываться редактор основной сущности таблицы. Такой подход может применяться для упрощения навигации - пользователи смогут открывать редактор одним кликом по некоторому ключевому атрибуту.

    • linkScreen - позволяет указать идентификатор экрана, который будет открыт по нажатию на ссылку, включенную свойством link.

    • linkScreenOpenType - задает режим открытия экрана (THIS_TAB, NEW_TAB или DIALOG).

    • linkInvoke - позволяет заменить открытие окна на вызов метода контроллера.

    • Элемент column может содержать вложенный элемент formatter для представления значения атрибута в виде, отличном от стандартного для данного Datatype:

      <column id="date">
          <formatter class="com.haulmont.cuba.gui.components.formatters.DateFormatter"
                     format="yyyy-MM-dd HH:mm:ss"/>
      </column>

  • rowsCount − необязательный элемент, создающий для таблицы компонент RowsCount, который позволяет загружать в таблицу данные постранично. Размер страницы задается путем ограничения количества записей в источнике данных методом CollectionDatasource.setMaxResults(). Как правило, это делает связанный с источником данных таблицы компонент Filter, однако при отсутствии универсального фильтра можно вызвать этот метод и напрямую из контроллера экрана.

    Компонент RowsCount может также отобразить общее число записей, возвращаемых текущим запросом в источнике данных, без извлечения этих записей. Для этого при щелчке пользователя на знаке "?" он вызывает метод AbstractCollectionDatasource.getCount(), что приводит к выполнению в БД запроса с такими же, как у текущего запроса условиями, но с агрегатной функцией COUNT(*) вместо результатов. Полученное число отображается вместо знака "?".

  • actions − необязательный элемент для описания действий, связанных с таблицей. Кроме описания произвольных действия поддерживаются следующие стандартные действия, определяемые перечислением ListActionType: create, edit, remove, refresh, add, exclude, excel.

  • buttonsPanel - необязательный элемент, создающий над таблицей контейнер ButtonsPanel для отображения кнопок действий.

Атрибуты table:

  • Атрибут multiselect позволяет задать режим множественного выделения строк в таблице. Если multiselect равен true, то пользователь может выделить несколько строк с помощью клавиатуры или мыши, удерживая клавиши Ctrl или Shift. По умолчанию режим множественного выделения отключен.

  • Атрибут sortable разрешает или запрещает сортировку в таблице. По умолчанию имеет значение true. Если сортировка разрешена, то при нажатии на название колонки справа от названия появляется значок /.

    При включенной с помощью элемента rowsCount (см. выше) страничной загрузке таблицы сортировка производится разными способами в зависимости от того, умещаются ли все записи на одной странице. Если умещаются, то сортировка производится в памяти, без обращений к БД. Если же страниц больше одной, то сортировка производится на базе данных путем отправки нового запроса с соответствующимORDER BY.

    Колонка таблицы может ссылаться на локальный атрибут или на связанную сущность. Например:

    <table id="ordersTable">
        <columns>
            <column id="customer.name"/> <!-- the 'name' attribute of the 'Customer' entity -->
            <column id="contract"/>      <!-- the 'Contract' entity -->
        </columns>
        <rows datasource="ordersDs"/>
    </table>

    В последнем случае, сортировка на базе данных производится по атрибутам, указанным в аннотации @NamePattern связанной сущности. Если у связанной сущности нет такой аннотации, то сортировка производится в памяти только в пределах текущей страницы.

    Если колонка таблицы ссылается на неперсистентный атрибут, то сортировка на базе данных производится по атрибутам, указанным в параметре related() аннотации @MetaProperty. Если такой параметр не указан, то сортировка производится в памяти только в пределах текущей страницы.

  • Атрибут presentations управляет механизмом представлений. Значение по умолчанию равно false. Когда значение атрибута равно true, то в верхнем правом углу таблицы появляется значок . Механизм представлений реализован только для блока Web Client.

  • Установка атрибута columnControlVisible в false запрещает пользователю скрывать колонки с помощью меню, выпадающего при нажатия на кнопку в правой части шапки таблицы. Флажками в меню отмечаются отображаемые в данный момент колонки.

  • Установка атрибута reorderingAllowed в false запрещает пользователю менять местами колонки, перетаскивая их с помощью мыши.

  • Атрибут contextMenuEnabled разрешает или запрещает показывать контекстное меню. По умолчанию атрибут имеет значение true. В контекстном меню отображаются действия таблицы (если они есть), и пункт Системная информация, содержащий информацию о выбранной сущности (если у пользователя есть разрешение cuba.gui.showInfo, см. руководство по подсистеме безопасности).

  • Если атрибуту multiLineCells таблицы присвоить значение true, то ячейки, содержащие текст с переносами строк, будут отображать его в несколько строк. В таком режиме в веб клиенте для правильной работы полосы прокрутки все строки текущей страницы таблицы будут загружены веб-браузером сразу, без ленивой загрузки видимой части таблицы. По умолчанию атрибут имеет значение false.

  • Атрибут aggregatable включает режим агрегации строк таблицы. Поддерживаются следующие операции:

    • SUM - сумма

    • AVG - среднее значение

    • COUNT - количество

    • MIN - минимальное значение

    • MAX - максимальное значение

    Для агрегируемых колонок необходимо указать элемент aggregation с атрибутом type, задающим функцию агрегации. Агрегированные значения столбцов выводятся в дополнительной строке вверху таблицы. Пример описания таблицы с агрегацией:

    <table id="itemsTable" aggregatable="true">
        <columns>
            <column id="product"/>
            <column id="quantity"/>
            <column id="amount">
                <aggregation type="SUM"/>
            </column>
        </columns>
        <rows datasource="itemsDs"/>
    </table>

    Для отображения агрегированного значения в виде, отличном от стандартного для данного Datatype, для него можно указать Formatter:

    <column id="amount">
        <aggregation type="SUM">
            <formatter class="com.company.sample.MyFormatter"/>
        </aggregation>
    </column>

    В дополнение к операциям, перечисленным выше, можно задать собственную стратегию агрегации путем создания класса, реализующего интерфейс AggregationStrategy, и передачи его методу setAggregation() класса Table.Column в составе экземпляра AggregationInfo. Например:

    public class TimeEntryAggregation implements AggregationStrategy<List<TimeEntry>, String> {
        @Override
        public String aggregate(Collection<List<TimeEntry>> propertyValues) {
            HoursAndMinutes total = new HoursAndMinutes();
            for (List<TimeEntry> list : propertyValues) {
                for (TimeEntry timeEntry : list) {
                    total.add(HoursAndMinutes.fromTimeEntry(timeEntry));
                }
            }
            return StringFormatHelper.getTotalDayAggregationString(total);
        }
        @Override
        public Class<String> getResultClass() {
            return String.class;
        }
    }

    AggregationInfo info = new AggregationInfo();
    info.setPropertyPath(metaPropertyPath);
    info.setStrategy(new TimeEntryAggregation());
    
    Table.Column column = weeklyReportsTable.getColumn(columnId);
    column.setAggregation(info);

  • Атрибут editable позволяет перевести таблицу в режим in-place редактирования ячеек. В этом режиме в колонках, имеющих атрибут editable = true, отображаются компоненты для редактирования значений атрибутов сущности, находящейся в источнике данных.

    Тип компонента для каждой редактируемой колонки выбирается автоматически на основании типа атрибута сущности. Например, для строковых и числовых атрибутов используется TextField, для Date - DateField, для перечислений - LookupField, для ссылок на другие сущности - PickerField.

    Для редактируемой колонки типа Date можно дополнительно указать атрибуты dateFormat или resolution аналогично описанным для DateField.

    Для редактируемой колонки, отображающей связанную сущность, можно дополнительно указать атрибуты optionsDatasource и captionProperty. При указании optionsDatasource вместо PickerField используется компонент LookupField.

    Произвольно настроить отображение ячеек, в том числе для редактирования содержимого, можно с помощью метода Table.addGeneratedColumn() - см. ниже.

Методы интерфейса Table:

  • getSelected(), getSingleSelected() - возвращают экземпляры сущностей, соответствующие выделенным в таблице строкам. Коллекцию можно получить вызовом метода getSelected(). Если ничего не выбрано, возвращается пустой набор. Если multiselect отключен, удобно пользоваться методом getSingleSelected(), возвращающим одну выбранную сущность или null, если ничего не выбрано.

  • Метод addGeneratedColumn() позволяет задать собственное представление данных в колонке. Он принимает два параметра: идентификатор колонки и реализацию интерфейсаTable.ColumnGenerator. Идентификатор может совпадать с одним из идентификаторов, указанных для колонок таблицы в XML-дескрипторе - в этом случае новая колонка вставляется вместо заданной в XML. Если идентификатор не совпадает ни с одной колонкой, создается новая справа.

    Метод generateCell() интерфейса Table.ColumnGenerator вызывается таблицей для каждой строки, и в него передается экземпляр сущности, отображаемой в данной строке. Метод generateCell() должен вернуть визуальный компонент, который и будет отображаться в ячейке.

    Пример использования:

    @Inject
    protected Table carsTable;
    
    @Inject
    protected ComponentsFactory componentsFactory;
    
    @Override
    public void init(Map<String, Object> params) {
        carsTable.addGeneratedColumn("colour", new Table.ColumnGenerator() {
            @Override
            public Component generateCell(Entity entity) {
                LookupPickerField field = componentsFactory.createComponent(LookupPickerField.NAME);
                field.setDatasource(carsTable.getItemDatasource(entity), "colour");
                field.setOptionsDatasource(coloursDs);
                field.addLookupAction();
                field.addOpenAction();
                return field;
            }
        });
    }

    В данном случае в ячейках колонки colour таблицы отображается компонент LookupPickerField. Компонент должен сохранять свое значение в атрибут colour сущности, экземпляр которой отображается в данной строке. Для этого у таблицы методом getItemDatasource() запрашивается источник данных для текущего экземпляра сущности, и передается компоненту LookupPickerField.

    Если в ячейке необходимо отобразить просто динамически сформированный текст, вместо компонента Label используйте класс Table.PlainTextCell. Это упростит отрисовку и сделает таблицу быстрее.

    Если в метод addGeneratedColumn() передан идентификатор колонки, не объявленной в XML-дескрипторе, то может понадобиться установить заголовок новой колонки следующим образом:

    carsTable.getColumn("colour").setCaption("Colour");

  • Метод setClickListener() может избавить от необходимости добавлять генерируемые колонки с компонентами, если нужно нарисовать что-либо в ячейках и получать оповещения когда пользователь кликает на эти ячейки. Имплементация класса CellClickListener, передаваемая в данный метод, получает текущий экземпляр сущности и идентификатор колонки. Содержимое ячеек будет завернуто в элемент span со стилем cuba-table-clickable-cell, который можно использовать для задания отображения ячеек.

  • Метод setStyleProvider() позволяет задать стиль отображения ячеек таблицы. Параметром метода должна быть реализация интерфейса Table.StyleProvider. Метод getStyleName() этого интерфейса вызывается таблицей отдельно для каждой строки и для каждой ячейки. Если метод вызван для строки, то первый параметр содержит экземпляр сущности, отображаемый этой строкой, а второй параметр null. Если же метод вызван для ячейки, то второй параметр содержит имя атрибута, отображаемого этой ячейкой.

    Пример задания стилей:

    @Inject
    protected Table customersTable;
    
    @Override
    public void init(Map<String, Object> params) {
        customersTable.setStyleProvider(new Table.StyleProvider() {
            @Nullable
            @Override
            public String getStyleName(Entity entity, @Nullable String property) {
                Customer customer = (Customer) entity;
                if (property == null) {
                    // style for row
                    if (hasComplaints(customer)) {
                        return"unsatisfied-customer";
                    }
                } else if (property.equals("grade")) {
                    // style for column "grade"
                    switch (customer.getGrade()) {
                        case PREMIUM: return "premium-grade";
                        case HIGH: return "high-grade";
                        case MEDIUM: return "medium-grade";
                        default: return null;
                    }
                }
                return null;
            }
        });
    }

    Далее нужно определить заданные для строк и ячеек стили в теме приложения. Подробная информация о создании темы находится вРаздел 4.5.7, «Создание темы приложения». Для веб-клиента новые стили определяются в файле styles.scss. Имена стилей, заданные в контроллере, совместно с префиксами, обозначающими строку или колонку таблицы, образуют CSS-селекторы. Например:

    .v-table-row-unsatisfied-customer {
      font-weight: bold;
    }
    
    .v-table-cell-content-premium-grade {
      background-color: red;
    }
    
    .v-table-cell-content-high-grade {
      background-color: green;
    }
    
    .v-table-cell-content-medium-grade {
      background-color: blue;
    }
  • Метод addPrintable() позволяет задать специфическое представление данных колонки при выводе в XLS-файл, осуществляемом стандартным действием excel или напрямую с помощью класса ExcelExporter. Метод принимает идентификатор колонки и реализацию интерфейса Table.Printable для нее. Например:

    ordersTable.addPrintable("customer", new Table.Printable<Customer, String>() {
        @Override
        public String getValue(Customer customer) {
            return "Name: " + customer.getName;
        }
    });

    Метод getValue() интерфейса Table.Printable должен возвращать данные, которые будут находиться в ячейке таблицы. Это может быть не только строка - метод может возвращать значения других типов, например, числовые данные или даты, и они будут представлены в XLS-файле соответствующим образом.

    Если форматированный вывод в XLS необходим для генерируемой колонки, нужно использовать реализацию интерфейса Table.PrintableColumnGenerator, передавая ее методу addGeneratedColumn(). Значение для вывода в ячейку XLS-документа задается в методе getValue() этого интерфейса:

    ordersTable.addGeneratedColumn("product", new Table.PrintableColumnGenerator<Order, String>() {
        @Override
        public Component generateCell(Order entity) {
            Label label = componentsFactory.createComponent(Label.NAME);
            Product product = order.getProduct();
            label.setValue(product.getName() + ", " + product.getCost());
            return label;
        }
    
        @Override
        public String getValue(Order entity) {
            Product product = order.getProduct();
            return product.getName() + ", " + product.getCost();
        }
    });

    Если генерируемой колонке тем или иным способом не задано представления Printable, то в случае, если колонке соответствует атрибут сущности, будет выведено его значение, в противном случае не будет выведено ничего.

  • Метод setItemClickAction() позволяет задать действие, выполняемое при двойном клике на строке таблицы. Если такое действие не задано, при двойном клике таблица пытается найти среди своих действий подходящее в следующем порядке:

    • Действие, назначенное на клавишу Enter посредством свойства shortcut.

    • Действие с именем edit.

    • Действие с именем view.

    Если такое действие найдено и имеет свойство enabled = true, оно выполняется.

  • Метод setEnterPressAction() позволяет задать действие, выполняемое при нажатии клавиши Enter. Если такое действие не задано, таблица пытается найти среди своих действий подходящее в следующем порядке:

    • Действие, назначенное методом setItemClickAction().

    • Действие, назначенное на клавишу Enter посредством свойства shortcut.

    • Действие с именем edit.

    • Действие с именем view.

    Если такое действие найдено и имеет свойство enabled = true, оно выполняется.

Атрибуты table:

Элементы table:

Атрибуты column:

Элементы column:

Атрибуты rows:

4.5.2.1.26. TextArea

Текстовая область − многострочное текстовое поле для редактирования текста.

XML-имя компонента: textArea

Компонент TextArea реализован для блоков Web Client и Desktop Client.

TextArea в основном повторяет функциональность TextField, за исключением того, что ему нельзя установить datatype. То есть TextArea предназначен для работы только с текстом и строковыми атрибутами сущностей.

Компонент TextArea имеет следующие специфические атрибуты:

  • cols и rows задают количество строк и столбцов текста:

    <textArea id="textArea" cols="20" rows="5" caption="msg://name"/>

    Значения width и height имеют приоритет над значениями cols и rows.

  • resizable - при задании атрибуту значения true и установке количества строк, больших одной, появляется возможность изменять размеры компонента:

    <textArea id="textArea" resizable="true" caption="msg://name" rows="5"/>

Атрибуты textArea:

4.5.2.1.27. TextField

Поле для редактирования текста. Может использоваться как для работы с атрибутами сущностей, так и для ввода и отображения произвольной текстовой информации.

XML-имя компонента: textField

Компонент текстового поля реализован для блоков Web Client и Desktop Client.

  • Пример текстового поля с заголовком, взятым из пакета локализованных сообщений:

    <textField id="nameField" caption="msg://name"/>

    На рисунке ниже показан вид простого текстового поля.

  • Для создания текстового поля, связанного с данными, необходимо использовать атрибуты datasource и property.

    <dsContext>
    <datasource id="customerDs" class="com.sample.sales.entity.Customer" view="_local"/>
    </dsContext>
    <layout>
    <textField datasource="customerDs" property="name" caption="msg://name"/>

    Как видно из примера, в экране описывается источник данных customerDs для некоторой сущности Покупатель (Customer), имеющей атрибут name. В компоненте текстового поля в атрибуте datasource указывается ссылка на источник данных, а в атрибуте property − название атрибута сущности, значение которого должно быть отображено в текстовом поле.

  • Если поле не связано с атрибутом сущности (то есть не указан источник данных и название атрибута), то можно указать тип данных с помощью атрибута datatype. Тип данных используется для форматирования значения поля. В качестве значения атрибута может быть указано любое имя типа данных, зарегистрированного в метаданных приложения - см. Раздел 4.2.2.3, «Datatype». Как правило, в TextField используются следующие типы данных:

    • decimal

    • double

    • int

    • long

    В качестве примера рассмотрим текстовое поле с типом данных Integer.

    <textField id="integerField" datatype="int" caption="msg://integerFieldName"/>

    Если в таком поле ввести значение, которое невозможно интерпретировать как целое число, то при потере фокуса полем будет выведено сообщение об ошибке и значение поля вернется на предыдущее:

  • Текстовому полю может быть назначен валидатор - класс, реализующий интерфейс Field.Validator. Валидатор позволяет дополнительно к datatype ограничить вводимую пользователем информацию. Например, для создания поля ввода положительных целых чисел нужно создать класс валидатора:

    public class PositiveIntegerValidator implements Field.Validator {
    @Override
    public void validate(Object value) throws ValidationException {
        Integer i = (Integer) value;
        if (i <= 0)
            throw new ValidationException("Value must be positive");
    }
    }

    и задать его для текстового поля с типом данных int в элементе validator:

    <textField id="integerField" datatype="int">
    <validator class="com.sample.sales.gui.PositiveIntegerValidator"/>
    </textField>

    В отличие от проверки вводимой строки на соответствие типу данных, валидация срабатывает не сразу при потере полем фокуса, а только при вызове у поля метода validate(). Это означает, что поле (и связанный с ним атрибут сущности) может некоторое время содержать значение, не удовлетворяющее условиям валидации (в приведенном примере неположительное число). Это не является проблемой, так как обычно поля редактирования с валидацией располагаются в экране редактирования, а он автоматически вызывает валидацию всех своих полей перед коммитом. Если же поле находится не в экране редактирования, то необходимо вызывать метод validate() поля в контроллере явно.

  • Если текстовое поле связано с атрибутом сущности (через datasource и property), и если для атрибута сущности в JPA-аннотации @Column указан параметр length, то TextField будет соответственно ограничивать максимальную длину вводимого текста.

    Если текстовое поле не связано с атрибутом, либо для него не определено значение length, либо это значение нужно переопределить, то для ограничения максимальной длины вводимого текста можно использовать атрибут maxLength. Значение "-1" означает отсутствие ограничения. Например:

    <textField id="shortTextField" maxLength="10"/>
  • По умолчанию текстовое поле отсекает пробелы в начале и конце введенной строки. То есть если пользователь ввел строку " aaa bbb " то значением поля, возвращаемым методом getValue() и сохраняемым в связанный атрибут сущности, будет строка "aaa bbb". Для того, чтобы отключить отсечение пробелов, используйте атрибут trim со значением false.

    Следует иметь в виду, что отсечение пробелов работает только при вводе нового значения. Если в значении связанного атрибута уже присутствуют пробелы, они будут отображаться, пока пользователь не изменит значение поля.

  • Текстовое поле всегда вместо введенной пустой строки возвращает null. Соответственно, при включенном атрибуте trim строка, состоящая из одних пробелов также превратится в null.

  • Атрибут inputPrompt задает строку, отображаемую в поле, если его значение равно null. Реализовано только для web клиента.

  • Метод setCursorPosition() используется для установки позиции курсора в указанный индекс (начинается с 0). После вызова метода поле принимает фокус ввода.

Атрибуты textField:

align | caption | datasource | datatype | description | editable | enable | height | id | inputPrompt | maxLength | property | required | requiredMessage | stylename | trim | visible | width

Элементы textField:

validator

4.5.2.1.28. TimeField

Поле для отображения и ввода времени.

XML-имя компонента: timeField.

Компонент TimeField реализован для блоков Web Client и Desktop Client.

  • Для создания поля даты, связанного с данными, необходимо использовать атрибуты datasource и property:

    <dsContext>
    <datasource id="orderDs" class="com.sample.sales.entity.Order" view="_local"/>
    </dsContext>
    <layout>
    <timeField datasource="orderDs" property="deliveryTime"/>

    Как видно из примера, в экране описывается источник данных orderDs для некоторой сущности Заказ (Order), имеющей атрибут deliveryTime. В компоненте ввода времени в атрибуте datasource указывается ссылка на источник данных, а в атрибуте property − название атрибута сущности, значение которого должно быть отображено в поле.

    Связанный атрибут сущности должен быть типа java.util.Date или java.sql.Time.

  • Формат отображения времени определяется типом данных time и задается в главном пакете локализованных сообщений в ключе timeFormat.

  • Формат отображения времени можно также задать в атрибуте timeFormat компонента. Это может быть как сама строка формата, так и ключ в пакете сообщений (с префиксом msg://).

  • Независимо от упомянутого выше формата отображением секунд можно управлять с помощью атрибута showSeconds. По умолчанию секунды отображаются, если формат содержит символы ss.

    <timeField datasource="orderDs" property="createTs" showSeconds="true"/>

Атрибуты timeField: align | caption | editable | enable | datasource | description | height | id | property | required | requiredMessage | showSeconds | stylename | timeFormat | visible | width

Элементы timeField: validator

4.5.2.1.29. TokenList

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

XML-имя компонента: tokenList

Компонент реализован для блоков Web Client и Desktop Client.

Пример описания компонента TokenList в XML-дескрипторе экрана:

<dsContext>
    <datasource id="orderDs"
                class="com.sample.sales.entity.Order"
                view="order-edit">
        <collectionDatasource id="productsDs" property="products"/>
    </datasource>
    <collectionDatasource id="allProductsDs"
                          class="com.sample.sales.entity.Product"
                          view="_minimal">
        <query>select p from sales$Product p order by p.name</query>
    </collectionDatasource>
</dsContext>
<layout>
    <tokenList id="productsList" datasource="productsDs" inline="true" width="500px">
        <lookup optionsDatasource="allProductsDs"/>
    </tokenList>

Здесь в элементе dsContext определен вложенный источник данных productsDs, содержащий коллекцию входящих в состав заказа продуктов. Кроме того, определен источник данных allProductsDs, содержащий коллекцию всех продуктов, имеющихся в базе данных. Компонент TokenList с идентификатором productsList отображает содержимое источника данных productsDs, а также позволяет изменять эту коллекцию, добавляя в него экземпляры из источника данных allProductsDs.

Атрибуты tokenList:

  • position - задает позиционирование раскрывающегося списка. Атрибут может принимать два значения: TOP, BOTTOM. По умолчанию TOP.

  • Атрибут inline задает отображение списка выбранных значений: вертикально или горизонтально. Значение true соответствует горизонтальному расположению, значение false − вертикальному. Так выглядит компонент с горизонтальным расположением значений:

  • simple - значение true позволяет убрать компонент выбора, оставляя только кнопку добавления. При нажатии на кнопку добавления сразу показывается экран списка экземпляров сущности, тип которой задан источником данных datasource. Идентификатор экрана выбора определяется по правилам, описанным для стандартного действия PickerField.LookupAction.

Элементы tokenList:

  • lookup − описатель компонента выбора значений.

    Атрибуты элемента lookup:

    • Атрибут lookup задает возможность выбора значений через экран выбора сущностей:

    • Атрибут lookupScreen задает идентификатор экрана для выбора значений в режиме lookup="true". Если данный атрибут не задан, то идентификатор экрана выбора определяется по правилам, описанным для стандартного действия PickerField.LookupAction.

    • Атрибут openType можно задать способ открытия экрана выбора, аналогично описанному для стандартного действия PickerField.LookupAction. По умолчанию - THIS_TAB.

    • Если значение атрибута multiselect установлено в true, то в мэп параметров экрана выбора в ключе MULTI_SELECT передается значение true. Этот признак можно использовать для установки в экране режима множественного выбора. Данный ключ определен в перечислении WindowParams, поэтому с ним удобно работать следующим образом:

      @Override
      public void init(Map<String, Object> params) {
          if (WindowParams.MULTI_SELECT.getBool(getContext())) {
              usersTable.setMultiSelect(true);
          }
      }

  • button − описатель кнопки добавления значений. Может содержать атрибуты caption и icon.

Все атрибуты tokenList:

Элементы tokenList:

Все атрибуты lookup:

Атрибуты button:

4.5.2.1.30. Tree

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

XML-имя компонента: tree

Компонент реализован для блоков Web Client и Desktop Client.

Для Tree в атрибуте datasource элемента treechildren должен быть указан hierarchicalDatasource. Объявление hierarchicalDatasource должно содержать атрибут hierarchyProperty - имя атрибута сущности, являющегося ссылкой на саму себя.

Пример описания компонента Tree в XML-дескрипторе экрана:

<dsContext>
<hierarchicalDatasource id="departmentsDs" class="com.sample.sales.entity.Department" view="browse"
                        hierarchyProperty="parentDept">
    <query>
        select d from sales$Department d order by d.createTs
    </query>
</hierarchicalDatasource>
</dsContext>
<layout>
<tree id="departmentsTree" width="100%" height="100%">
    <treechildren datasource="departmentsDs" captionProperty="name"/>
</tree>

В атрибуте captionProperty элемента treechildren можно задать имя свойства сущности, отображаемого в дереве. Если этот атрибут не определен, то будет отображаться имя экземпляра сущности.

Метод setItemClickAction() позволяет задать действие, которое будет выполнено при двойном клике по узлу дерева.

Атрибуты tree:

Элементы tree:

Атрибуты treechildren:

4.5.2.1.31. TreeTable

Компонент TreeTable − иерархическая таблица, отображающая в первой колонке древовидную структуру. Предназначена для работы с сущностями, которые содержат ссылки на самих себя. Это могут быть например, файловая система или организационная структура предприятия.

XML-имя компонента: treeTable

Компонент реализован для блоков Web Client и Desktop Client.

Для TreeTable в атрибуте datasource элемента rows должен быть указан hierarchicalDatasource. Объявление hierarchicalDatasource должно содержать атрибут hierarchyProperty - имя атрибута сущности, являющегося ссылкой на саму себя.

Пример описания таблицы в XML-дескрипторе экрана:

<dsContext>
<hierarchicalDatasource id="tasksDs" class="com.sample.sales.entity.Task" view="browse"
                        hierarchyProperty="parentTask">
    <query>
        select t from sales$Task t
    </query>
</hierarchicalDatasource>
</dsContext>
<layout>
<treeTable id="tasksTable" width="100%">
    <columns>
        <column id="name"/>
        <column id="dueDate"/>
        <column id="assignee"/>
    </columns>
    <rows datasource="tasksDs"/>
</treeTable>

Функциональность TreeTable аналогична простой таблице Table.

Атрибуты treeTable:

Элементы treeTable:

Атрибуты column:

Элементы column:

Атрибуты rows:

4.5.2.1.32. TwinColumn

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

XML-имя компонента: twinColumn

Компонент реализован только для блока Web Client.

Пример использования компонента twinColumn для выбора экземпляров сущности:

<dsContext>
<datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
<collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
    <query>select c from sample$Colour c</query>
</collectionDatasource>
</dsContext>
<layout>
<twinColumn id="coloursField" optionsDatasource="coloursDs" addAllBtnEnabled="true"/>

В данном случае компонент coloursField отобразит имена экземпляров сущности Colour, находящихся в источнике данных coloursDs, а его метод getValue() вернет коллекцию выбранных экземпляров сущности.

Атрибут addAllBtnEnabled задает отображение кнопок, позволяющих перемещать между списками все опции сразу.

Атрибут columns используется для задания количества символов в строке, а атрибут rows − для задания количества строк текста в каждом списке.

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

Список опций компонента TwinColumn может быть задан произвольно с помощью методов setOptionsList() и setOptionsMap(), аналогично описанному для компонента OptionsGroup.

Атрибуты twinColumn:

Элементы twinColumn:

4.5.2.2. Контейнеры

BoxLayout

ButtonsPanel

IFrame

GridLayout

GroupBoxLayout

ScrollBoxLayout

SplitPanel

TabSheet

4.5.2.2.1. BoxLayout

BoxLayout представляет собой контейнер с последовательным размещением компонентов.

Существует три типа BoxLayout, определяемых именем XML-элемента:

  • hbox − горизонтальное расположение компонентов.

    <hbox spacing="true" margin="true">
    <dateField datasource="orderDs" property="date"/>
    <lookupField datasource="orderDs" property="customer" optionsDatasource="customersDs"/>
    <textField datasource="orderDs" property="amount"/>
    </hbox>
  • vbox − вертикальное расположение компонентов. vbox имеет 100% ширину по умолчанию.

    <vbox spacing="true" margin="true">
    <dateField datasource="orderDs" property="date"/>
    <lookupField datasource="orderDs" property="customer" optionsDatasource="customersDs"/>
    <textField datasource="orderDs" property="amount"/>
    </vbox>
  • flowBox − горизонтальное расположение компонентов с переносом вниз. При недостатке места по горизонтали непомещающиеся компоненты будут перенесены "на следующую строку" (поведение аналогично Swing FlowLayout).

    <flowBox spacing="true" margin="true">
    <dateField datasource="orderDs" property="date"/>
    <lookupField datasource="orderDs" property="customer" optionsDatasource="customersDs"/>
    <textField datasource="orderDs" property="amount"/>
    </flowBox>

В элементах hbox, vbox, flowBox могут быть использованы следующие XML-атрибуты:

4.5.2.2.2. ButtonsPanel

ButtonsPanel - контейнер, унифицирующий использование и размещение компонентов (чаще всего кнопок) для управления данными в таблице.

XML-имя компонента: buttonsPanel.

Пример описания ButtonsPanel в XML-дескрипторе экрана:

<table id="customersTable"
   editable="false" width="100%">
<actions>
    <action id="create"/>
    <action id="edit"/>
    <action id="remove"/>
    <action id="excel"/>
</actions>
<buttonsPanel>
    <button action="customersTable.create"/>
    <button action="customersTable.edit"/>
    <button action="customersTable.remove"/>
    <button action="customersTable.excel"/>
</buttonsPanel>
<columns>
    <column id="name"/>
    <column id="email"/>
</columns>
<rows datasource="customersDs"/>
</table>

Элемент buttonsPanel можно разместить как внутри table, так и в произвольном месте экрана.

Если buttonsPanel находится внутри table, то она комбинируется с компонентом rowsCount таблицы, тем самым оптимально расходуя место по вертикали. Кроме того, в этом случае при открытии экрана выбора методом IFrame.openLookup() (например, из компонента PickerField) панель кнопок скрывается.

Атрибут alwaysVisible служит для отключения скрытия панели в экране выбора при его открытии методом IFrame.openLookup(). Если значение атрибута равно true, то панель с кнопками не скрывается. По умолчанию значение атрибута равно false.

Атрибуты buttonsPanel:

4.5.2.2.3. GridLayout

GridLayout - контейнер, располагающий компоненты по сетке.

XML-имя компонента: grid.

Пример использования контейнера:

<grid spacing="true">
<columns count="4"/>
<rows>
    <row>
        <label value="Date"/>
        <dateField datasource="orderDs" property="date"/>
        <label value="Customer"/>
        <lookupField datasource="orderDs" property="customer" optionsDatasource="customersDs"/>
    </row>
    <row>
        <label value="Amount"/>
        <textField datasource="orderDs" property="amount"/>
    </row>
</rows>
</grid>

Элементы grid:

  • columns - обязательный элемент, описывает колонки сетки. Должен либо иметь атрибут count, либо вложенные элементы column для каждой колонки.

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

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

    Пример сетки, в которой вторая и четвертая колонки занимают все лишнее место по горизонтали, причем четвертая колонка забирает себе в три раза больше лишнего места:

    <grid spacing="true" width="100%">
    <columns>
        <column/>
        <column flex="1"/>
        <column/>
        <column flex="3"/>
    </columns>
    <rows>
        <row>
            <label value="Date"/>
            <dateField datasource="orderDs" property="date" width="100%"/>
            <label value="Customer"/>
            <lookupField datasource="orderDs" property="customer" optionsDatasource="customersDs" width="100%"/>
        </row>
        <row>
            <label value="Amount"/>
            <textField datasource="orderDs" property="amount" width="100%"/>
        </row>
    </rows>
    </grid>

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

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

  • rows − обязательный элемент, содержит последовательность строк. Каждая строка определяется в своем элементе row.

    Элемент row может содержать атрибут flex, аналогичный описанному для column, но влияющий на распределение лишнего места по вертикали при заданной общей высоте сетки.

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

Любой компонент, находящийся в контейнере grid, может иметь атрибуты colspan и rowspan. Эти атрибуты задают соответственно сколько колонок и строк будет занимать данный компонент. Например, так можно растянуть поле Field3 на три колонки:

<grid spacing="true">
<columns count="4"/>
<rows>
    <row>
        <label value="Field1"/>
        <textField/>
        <label value="Field2"/>
        <textField/>
    </row>
    <row>
        <label value="Field3"/>
        <textField colspan="3" width="100%"/>
    </row>
</rows>
</grid>

В результате компоненты будут располагаться следующим образом:

Атрибуты grid:

Элементы grid:

columns    
rows    

Атрибуты columns:

count    

Атрибуты column:

flex    

Атрибуты row:

flex    
visible    
4.5.2.2.4. GroupBoxLayout

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

XML-имя компонента: groupBox.

Пример описание контейнера в XML-дескрипторе экрана:

<groupBox caption="Order">
<dateField datasource="orderDs" property="date" caption="Date"/>
<lookupField datasource="orderDs" property="customer"
             optionsDatasource="customersDs" caption="Customer"/>
<textField datasource="orderDs" property="amount" caption="Amount"/>
</groupBox>

Атрибуты groupBox:

  • caption - заголовок группы.

  • orientation - задает направление расположения вложенных компонентов − horizontal или vertical. По умолчанию vertical.

  • collapsable − значение true позволяет пользователю скрывать содержимое компонента с помощью значков /.

  • collapsed − если указано значение true, то содержимое компонента будет свернуто сразу после открытия экрана. Используется совместно с collapsable="true".

    Пример свернутого GroupBox:

Контейнер groupBox по умолчанию имеет ширину 100% аналогично vbox.

Все атрибуты groupBox:

4.5.2.2.5. IFrame

Элемент iframe предназначен для включения в экран фрейма.

Атрибуты:

  • src − путь к XML-дескриптору фрейма.

  • screen - идентификатор фрейма в screens.xml (если фрейм зарегистрирован).

Должен быть указан один из этих атрибутов. Если указано оба, фрейм будет загружен из явно указанного в src файла.

Другие атрибуты iframe:

4.5.2.2.6. ScrollBoxLayout

ScrollBoxLayout − контейнер, который позволяет прокручивать свое содержимое.

XML-имя компонента: scrollBox

Пример описание контейнера с прокруткой в XML-дескрипторе экрана:

<groupBox caption="Order" width="300" height="170">
<scrollBox width="100%" height="100%" spacing="true" margin="true">
    <dateField datasource="orderDs" property="date" caption="Date"/>
    <lookupField datasource="orderDs" property="customer" optionsDatasource="customersDs" caption="Customer"/>
    <textField datasource="orderDs" property="amount" caption="Amount"/>
 </scrollBox>
</groupBox>
  • С помощью атрибута orientation можно задавать направление расположения вложенных компонентов − horizontal или vertical. По умолчанию vertical.

  • Атрибут scrollBars позволяет настраивать полосы прокрутки. Может принимать значения horizontal, vertical - для прокрутки по горизонтали и вертикали соответственно, both - для прокрутки во всех направлениях. Установка значения none запрещает прокрутку в любом направлении

Вложенные в scrollBox компоненты должны иметь фиксированные размеры или размеры по умолчанию. Нельзя устанавливать height="100%" или width="100%".

В то же время scrollBox не может вычислять свои собственные размеры по содержимому. Ему нужно либо указать абсолютные размеры, либо растянуть в родительском контейнере, установив height="100%"