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

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

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

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

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

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

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

Чтобы решить эти проблемы, в подходе 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 останется верной.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

dateFormat=dd.MM.yyyy

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>

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

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

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

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

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

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

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

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

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

Подробная структура 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>

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

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

Для создания управляемого бина достаточно добавить классу 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 используется во всех стандартных блоках приложения.

Ссылку на бин можно получить с помощью инжекции или класса 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, который и содержит основную бизнес-логику.

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

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

Методы Resources:

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

Методы Scripting:

Кэш скомпилированных классов можно очистить во время выполнения с помощью JMX-бина CachingFacadeMBean.

См. также Раздел 4.2.5.2.5, «ScriptingManagerMBean»

Обеспечивает авторизацию - проверку прав пользователя на различные объекты системы. Перед вызовом соответствующих методов UserSession выполняется поиск исходного мета-класса сущности, что является важным при наличии расширений. Кроме методов, дублирующих методы UserSession, данный интерфейс имеет методы isEntityAttrReadPermitted() и isEntityAttrUpdatePermitted(), предназначенные для определения доступности пути к атрибуту с учетом доступности атрибутов и сущностей, входящих в этот путь.

Подробнее см. Раздел 4.2.10, «Аутентификация пользователей»

Обеспечивает получение текущего времени. Применение new Date() и т.п. в прикладном коде не рекомендуется.

Примеры:

@Inject
protected TimeSource timeSource;
...
Date date = timeSource.currentTimestamp();

long startTime = AppBeans.get(TimeSource.class).currentTimeMillis();

Обеспечивает получение объекта сессии текущего пользователя. Подробнее см. Раздел 4.2.10, «Аутентификация пользователей»

Обеспечивает получение значений UUID, в том числе для идентификаторов сущностей. Применение UUID.randomUUID() в прикладном коде не рекомендуется.

Для вызова из статического контекста можно использовать класс UuidProvider, который имеет также дополнительный метод fromString(), работающий быстрее, чем стандартный метод UUID.fromString().

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

DataManager всегда стартует новую транзакцию и по завершении работы выполняет коммит, таким образом возвращая сущности в detached состоянии.

Методы DataManager:

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

<task:scheduled-tasks scheduler="scheduler">
      <task:scheduled ref="cuba_QueryResultsManager" method="deleteForInactiveSessions" fixed-rate="600000"/>
  </task:scheduled-tasks>

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

Некоторые блоки приложения определяют JMX-интерфейсы для доступа к свойствам приложения. В частности, в блоках Middleware, Web Client и Web Portal имеется JMX-интерфейс ConfigStorageMBean , позволяющий получить и задать значение любого свойства во время работы приложения.

Свойства, определяющие конфигурацию и параметры развертывания, задаются в специальных файлах свойств, имеющих имя вида *-app.properties. Каждый блок приложения имеет набор таких файлов, включающий в себя файлы из базовых проектов платформы и файл текущего приложения. Набор файлов свойств определяется следующим образом:

Например, набор файлов свойств блока 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.

Параметры времени выполнения хранятся в таблице SYS_CONFIG базы данных.

Такие свойства имеют следующие особенности:

Хранящиеся в БД свойства кэшируются на уровне Middleware. Очистить кэш можно с помощью JMX-интерфейсов ConfigStorageMBean методом clearCache() или CachingFacadeMBean методом clearConfigStorageCache().

Следует иметь в виду, что на клиентском уровне чтение свойства, хранящегося в БД, приводит к запросу к Middleware, что менее эффективно, чем чтение локального свойства из app.properties. Для уменьшения количества таких запросов клиент кэширует все свойства, хранящиеся в БД, на время жизни экземпляра реализации конфигурационного интерфейса. Поэтому если, например, в некотором экране UI необходимо несколько раз обратиться к свойствам одного конфигурационного интерфейса, лучше получить ссылку на него при инициализации экрана, и сохранить в поле для последующих обращений к одному и тому же экземпляру.

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

Пример получения значения таймаута транзакции в блоке Middleware:

@Inject
private ServerConfig serverConfig;

public void doSomething() {
  int timeout = serverConfig.getDefaultQueryTimeoutSec();
  ...
}

При невозможности инжекции можно получить ссылку на конфигурационный интерфейс через Configuration:

int timeout = AppBeans.get(Configuration.class)
  .getConfig(ServerConfig.class)
  .getDefaultQueryTimeoutSec();

@Source(type = SourceType.DATABASE)
public interface SalesConfig extends Config {

  @Property("sales.companyName")
  String getCompanyName();
}

@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();

@Default("sec$User-98e5e66c-3ac9-11e2-94c1-3860770d7eaf-browse")
User getAdminUser();

@Default("sec$Role-a294aef0-3ac9-11e2-9433-3860770d7eaf")
Role getAdminRole();

Пакет сообщений представляет собой набор файлов свойств с именами вида 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, со следующими особенностями:

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

Каждый стандартный блок приложения определяет для себя один главный пакет сообщений. Для блоков клиентского уровня этот пакет содержит названия пунктов главного меню и общих элементов UI (например, названия кнопок OK и Cancel). Для всех блоков приложения, включая Middleware, главный пакет определяет форматы преобразований Datatype .

Для указания главного пакета сообщений используется свойство приложения cuba.mainMessagePack . Значением свойства может быть либо один пакет, либо список пакетов, разделенный пробелами. Например:

cuba.mainMessagePack=com.haulmont.cuba.web com.abc.sales.web

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

Для отображения в 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 . Кроме того, названия сущностей и атрибутов могут быть также получены следующими методами:

Для локализации названий и значений перечислений необходимо в пакет сообщений, находящийся в 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.

Основной элемент подсистемы контроля доступа в 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(). Последний может также возвращать следующие параметры сессии, как если бы они были атрибутами:

Атрибуты реплицируются в кластере Middleware так же, как и все остальные данные сессии.

Стандартный вариант входа пользователя:

Алгоритм хэширования паролей реализуется бином типа EncryptionModule и задается в свойстве приложения cuba.passwordEncryptionModule . По умолчанию - SHA-1.

Возможен вариант, когда пароль пользователя (точнее, хэш пароля) не хранится в базе данных, а проверяется внешними средствами, например, путем интеграции с ActiveDirectory. В этом случае фактически аутентификацию выполняет клиентский блок, а Middleware "доверяет" клиенту, создавая сессию по одному только логину пользователя без пароля методом LoginService.loginTrusted(). Метод loginTrusted() требует выполнения следующих условия:

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

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

Вход в систему для процессов внутри Middleware выполняется вызовом LoginWorker.loginSystem() с передачей логина пользователя (без пароля), от имени которого будет работать данный процесс. В результате создается объект UserSession , который будет закэширован в данном блоке Middleware и не будет реплицироваться в кластере.

Более подробно аутентификация процессов внутри Middleware рассмотрена в разделе Раздел 4.4.2, «Системная аутентификация»

Экземпляр класса SecurityContext хранит информацию о пользовательской сессии для текущего потока выполнения. Он создается и передается в метод AppContext.setSecurityContext() в следующие моменты:

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

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

final SecurityContext securityContext = AppContext.getSecurityContext();
executor.submit(new Runnable() {
  public void run() {
      AppContext.setSecurityContext(securityContext);
      // business logic here
  }
});

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

Платформа содержит специальный класс недекларируемого исключения SilentException, который можно использовать для прерывания хода выполнения без выдачи каких-либо сообщений пользователю или в лог. SilentException объявлен в модуле global, поэтому доступен как на 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, указав в ней тип логгирования:

Например:

@SupportedByClient
@Logging(Logging.Type.BRIEF)
public class FinancialTransactionException extends Exception {
...

Необработанные исключения в блоках 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");
    }
...

На уровне прикладного проекта можно реализовать работу с любой СУБД, поддерживаемой фреймворком ORM (OpenJPA). Для этого достаточно выполнить следующее:

В дополнение к свойству приложения 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 

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)^

Groovy-скрипты обновления имеют следующую структуру:

На вход 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()
  }
})

Имена интерфейсов сервисов должны заканчиваться на Service, имена классов реализации на ServiceBean.

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

Для того чтобы вызывать сервис, в клиентском блоке приложения для него должен быть создан соответствующий прокси-объект. Делается это путем объявления имени и интерфейса сервиса в параметрах фабрики прокси-объектов. Для блока 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);

DataService является фасадом для вызова серверной релизации DataManager с клиентского уровня. DataService не рекомендуется использовать в прикладном коде. Вместо него и на клиентском уровне, и на Middleware следует использовать DataManager.

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

Методы PersistenceTools:

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

MyPersistenceTools tools = persistence.getTools();
tools.foo();

((MyPersistenceTools) persistence.getTools()).foo();

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

Методы PersistenceHelper:

Интерфейс, определяющий методы для конвертации данных между значениями атрибутов модели данных и параметрами и результатами запросов JDBC. Объект данного интерфейса можно получить методом Persistence.getDbTypeConverter().

Методы DbTypeConverter:

EntityManager - основной интерфейс ORM, служит для управления персистентными сущностями.

Ссылку на EntityManager можно получить через интерфейс Persistence, вызовом метода getEntityManager(). Полученный экземпляр EntityManager привязан к текущей транзакции, то есть все вызовы getEntityManager() в рамках одной транзакции возвращают один и тот же экземпляр EntityManager. После завершения транзакции обращения к данному экземпляру невозможны.

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

Интерфейс EntityManager, используемый в CUBA-приложениях, в основном повторяет стандартный javax.persistence.EntityManager. Рассмотрим его основные методы:

Загрузка по требованию (lazy loading) позволяет загружать связанные сущности отложенно, т.е. только в момент первого обращения к их свойствам.

Загрузка по требованию в сумме порождает больше запросов к БД, чем жадная загрузка (eager fetching), однако нагрузка при этом растянута во времени.

Загрузка по требованию работает только для экземпляра в состоянии Managed, то есть внутри транзакции, загрузившей данный экземпляр.

Для выполнения JPQL запросов предназначен интерфейс Query, ссылку на который можно получить у текущего экземпляра EntityManager вызовом метода createQuery(). Если запрос предполагается использовать для извлечения сущностей, рекомендуется вызывать createQuery() с передачей типа результата, что приведет к созданию TypedQuery.

Методы Query в основном соответствуют методам стандартного интерфейса javax.persistence.Query . Рассмотрим отличия.

При выполнении запроса через 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, которые могут отрицательно сказаться на производительности.

select c from sales$Customer c where c.name like :name

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 драйвера:

Параметры этого типа также должны задаваться либо как 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».

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

Слушатель представляет собой класс, реализующий один или несколько интерфейсов пакета com.haulmont.cuba.core.listener. Слушатель будет реагировать на события типов, соответствующих реализуемым интерфейсам.

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-мя способами:

Для всех экземпляров некоторого класса сущности извлекается из контекста Spring или создается и кэшируется один экземпляр слушателя определенного типа, поэтому слушатель не должен иметь состояния.

Если для сущности объявлены несколько слушателей одного типа (например, аннотациями класса сущности и его предков, плюс динамически), то их вызов будет выполняться в следующем порядке:

Программное управление транзакциями осуществляется с помощью интерфейса 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 можно вызвать только один раз, так как после выполнения кода класса-действия транзакция завершается.

Любой метод управляемого бина Middleware можно пометить аннотацией @org.springframework.transaction.annotation.Transactional, что вызовет автоматическое создание транзакции при вызове этого метода. В таком методе не нужно вызывать Persistence.createTransaction(), а можно сразу получать EntityManager и работать с ним.

Для аннотации @Transactional можно указать параметры. Основным параметром является режим создания транзакции - Propagation. Значение REQUIRED соответствует getTransaction(), значение REQUIRES_NEW - createTransaction(). По умолчанию REQUIRED.

Декларативное управление транзакциями позволяет уменьшить количество boilerplate кода, однако имеет следующий недостаток: коммит транзакции происходит вне прикладного кода, что часто затрудняет отладку, т.к. скрывается момент отправки изменений в БД и перехода сущностей в состояние Detached. Кроме того, следует иметь в виду, что декларативная разметка сработает только в случае вызова метода контейнером, т.е. вызов транзакционного метода из другого метода того же самого объекта не приведет к старту транзакции.

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

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

При программном управлении транзакциями таймаут включается путем передачи объекта TransactionParams в метод Persistence.createTransaction(). Например:

Transaction tx = persistence.createTransaction(new TransactionParams().setTimeout(2));

При декларативном управлении транзакциями используется параметр timeout аннотации @Transactional, например:

@Transactional(timeout = 2)
public void someServiceMethod() {
...

Таймаут по умолчанию может быть задан в свойстве приложения cuba.defaultQueryTimeoutSec .

В данном разделе рассматриваются основные типы экранов:

XML-дескриптор - это файл формата XML, описывающий источники данных и расположение визуальных компонентов экрана.

Схема XML доступна по адресу http://schemas.haulmont.com/cuba/5.6/window.xsd

Рассмотрим структуру дескриптора.

window − корневой элемент.

Атрибуты window:

Элементы window:

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

Контроллер должен быть унаследован от одного из следующих базовых классов: