3.2.6.2. DataManager

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

Руководство Introduction to Working with Data содержит различные варианты использования программного доступа к данным с помощью DataManager API.

В разделе DataManager vs. EntityManager приведена информация о различиях между DataManager и EntityManager.

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

Методы DataManager:

  • load(Class) - загружает сущности указанного типа. Данный метод является точкой входа в fluent API:

    @Inject
    private DataManager dataManager;
    
    private Book loadBookById(UUID bookId) {
        return dataManager.load(Book.class).id(bookId).view("book.edit").one();
    }
    
    private List<BookPublication> loadBookPublications(UUID bookId) {
        return dataManager.load(BookPublication.class)
            .query("select p from library_BookPublication p where p.book.id = :bookId")
            .parameter("bookId", bookId)
            .view("bookPublication.full")
            .list();
    }
  • loadValues(String query) - загружает пары ключ-значение по запросу, возвращающему скалярные значения. Данный метод является точкой входа в fluent API:

    List<KeyValueEntity> list = dataManager.loadValues(
            "select o.customer, sum(o.amount) from demo_Order o " +
            "where o.date >= :date group by o.customer")
        .store("legacy_db") (1)
        .properties("customer", "sum") (2)
        .parameter("date", orderDate)
        .list();
    1 - укажите хранилище, в котором находится сущность. Данный метод можно опустить, если сущность находится в главном хранилище.
    2 - перечислите имена атрибутов результирующей KeyValueEntity. Порядок имен должен соответствовать колонкам результирующего набора в запросе.
  • loadValue(String query, Class valueType) - загружает единственное значение по запросу. Данный метод является точкой входа в fluent API:

    BigDecimal sum = dataManager.loadValue(
            "select sum(o.amount) from demo_Order o " +
            "where o.date >= :date group by o.customer", BigDecimal.class)
        .store("legacy_db") (1)
        .parameter("date", orderDate)
        .one();
    1 - укажите хранилище, в котором находится сущность. Данный метод можно опустить, если сущность находится в главном хранилище.
  • load(LoadContext), loadList(LoadContext) - загружает сущности в соответствии с параметрами переданного объекта LoadContext. В LoadContext обязательно должен быть передан либо JPQL-запрос, либо идентификатор сущности. Если передано и то и другое, используется запрос, а идентификатор игнорируется. Примеры:

    @Inject
    private DataManager dataManager;
    
    private Book loadBookById(UUID bookId) {
        LoadContext<Book> loadContext = LoadContext.create(Book.class)
                .setId(bookId).setView("book.edit");
        return dataManager.load(loadContext);
    }
    
    private List<BookPublication> loadBookPublications(UUID bookId) {
        LoadContext<BookPublication> loadContext = LoadContext.create(BookPublication.class)
                .setQuery(LoadContext.createQuery("select p from library_BookPublication p where p.book.id = :bookId")
                    .setParameter("bookId", bookId))
                .setView("bookPublication.full");
        return dataManager.loadList(loadContext);
    }
  • loadValues(ValueLoadContext) - загружает список пар ключ-значение. Метод принимает объект ValueLoadContext, в котором задается запрос и список ключей. Возвращаемый список содержит экземпляры KeyValueEntity. Например:

    ValueLoadContext context = ValueLoadContext.create()
            .setQuery(ValueLoadContext.createQuery(
                        "select o.customer, sum(o.amount) from demo_Order o " +
                        "where o.date >= :date group by o.customer")
                .setParameter("date", orderDate))
            .addProperty("customer")
            .addProperty("sum");
    List<KeyValueEntity> list = dataManager.loadValues(context);
  • getCount(LoadContext) - возвращает количество записей для запроса, переданного в метод. Когда возможно, для максимальной производительности, стандартная реализация в классе RdbmsStore выполняет запрос select count() с условиями исходного запроса.

  • commit(CommitContext) - сохраняет в базе данных набор сущностей, переданный в объекте CommitContext. Отдельно указываются коллекции сущностей, которые нужно сохранить и которые нужно удалить.

    Метод возвращает набор экземпляров сущностей, возвращенных из метода EntityManager.merge(), то есть по сути свежие экземпляры, только что обновленные в БД. Дальнейшая работа должна производиться именно с этими возвращенными экземплярами, чтобы предотвратить потерю данных или исключения оптимистичной блокировки. Для того, чтобы обеспечить наличие нужных атрибутов у возвращенных сущностей, с помощью мэп CommitContext.getViews() можно указать представление для каждого сохраняемого экземпляра.

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

    Примеры сохранения коллекций сущностей:

    @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.addInstanceToCommit(bookInstance, view);
        }
        return dataManager.commit(commitContext);
    }
  • reload(Entity, View) - удобный метод для перезагрузки экземпляра сущности с требуемым представлением. Делегирует выполнение методу load().

  • remove(Entity) - удаляет экземпляр сущности из базы данных. Делегирует выполнение методу commit().

  • create(Class) - создает экземпляр данной сущности в памяти. Этот метод просто делегирует в Metadata.create().

  • getReference(Class, Object) - возвращает экземпляр сущности, который может быть использован в качестве ссылки на объект, существующий в базе данных.

    Например, если вы создаете экземпляр сущности User, вам необходимо установить ссылку на Group, в которую данный пользователь будет входить. Если вам известен id группы, то вы могли бы загрузить данную группу из БД. Данный метод позволяет получить экземпляр Group без ненужного обращения к БД:

    user.setGroup(dataManager.getReference(Group.class, groupId));
    dataManager.commit(user);

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

    dataManager.remove(dataManager.getReference(Customer.class, customerId));
Запросы

При работе с реляционными базами данных для загрузки данных используются запросы на JPQL. В разделах Функции JPQL, Поиск подстроки без учета регистра и Макросы в JPQL приведена информация о том, как JPQL в CUBA отличается от стандартного JPA. Кроме того, имейте в виду, что DataManager может выполнять только "select"-запросы.

Метод query() fluent-интерфейса принимает строку запроса как в полном, так и в сокращенном формате. Сокращенный запрос формируется следующим образом:

  • Выражение "select <alias>" всегда можно опустить.

  • Если выражение "from" содержит одну сущность, и вам не нужен особенный алиас, то выражение "from <entity> <alias> where" можно опустить. В этом случае фреймворк будет использовать алиас e.

  • Можно использовать позиционные параметры и передавать их значения прямо в метод query() в дополнительных аргументах.

Например:

// named parameter
dataManager.load(Customer.class)
        .query("e.name like :name")
        .parameter("name", value)
        .list();

// positional parameter
dataManager.load(Customer.class)
        .query("e.name like ?1", value)
        .list();

// case-insensitive positional parameter
dataManager.load(Customer.class)
        .query("e.name like ?1 or e.email like ?1", "(?i)%joe%")
        .list();

// multiple positional parameters
dataManager.load(Order.class)
        .query("e.date between ?1 and ?2", date1, date2)
        .list();

// omitting "select" and using a positional parameter
dataManager.load(Order.class)
        .query("from sales_Order o, sales_OrderLine l " +
                "where l.order = o and l.product.name = ?1", productName)
        .list();

Имейте в виду, что позиционные параметры поддерживаются только в fluent-интерфейсе. В LoadContext.Query можно использовать только именованные параметры.

Транзакции

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

Частичные сущности

Частичная сущность - это экземпляр сущности, в котором может быть загружена только часть локальных атрибутов. По умолчанию, DataManager загружает частичные сущности в соответствии с указанными представлениями. (на самом деле, RdbmsStore просто устанавливает свойство loadPartialEntities у представления в true и передает его дальше в EntityManager).

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