4.2.6.10. DataManager

DataManager interface provides CRUD functionality on both middle and client tiers. It is a universal tool for loading entity graphs from the database and saving changes applied to detached entity instances.

DataManager always starts a new transaction and commits it on operation completion, thus returning entities in the detached state.

DataManager always applies security restrictions when invoked from a client, and ignores them by default when invoked from middleware code. If you want to check security when using DataManager in your middleware code, obtain a wrapper via DataManager.secure() method and call its methods. Alternatively, you can set the cuba.dataManagerChecksSecurityOnMiddleware application property to turn on security check for the whole application.

DataManager methods are listed below:

  • load(), loadList() – loads a graph of entities according to the parameters of the LoadContext object passed to it.

    LoadContext must include either a JPQL query or an entity identifier. If both are defined, the query is used, and the identifier is ignored. The rules for queries creation are similar to those described in Executing JPQL Queries . The difference is that the query in LoadContext may only use named parameters; positional parameters are not supported.

    load() and loadList() methods check user permission EntityOp.READ for the entity being loaded. Additionally, loading entities from DB is subject for access group constraints.

    Examples of loading entities in the screen controller:

    @Inject
private DataManager dataManager;

private Book loadBookById(UUID bookId) {
    LoadContext loadContext = LoadContext.create(Book.class)
            .setId(bookId).setView("book.edit");
    return dataManager.load(loadContext);
}

private List<BookPublication> loadBookPublications(UUID bookId) {
    LoadContext 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);
}

  • commit() – saves the set of entities passed in CommitContext to the database. Collections of entities for updating and deletion must be specified separately.

    The method returns the set of entity instances returned by EntityManager.merge(); essentially these are fresh instances just updated in DB. Further work should be performed with these returned instances to prevent data loss or optimistic locking. You can ensure that required attributes are present in the returned entities by setting a view for each saved instance using CommitContext.getViews() map.

    This method checks user permissions EntityOp.UPDATE for the updated entities and EntityOp.DELETE for the deleted ones.

    Examples for saving a collection of entities:

    @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() - convenience methods to reload a specified instance from the database with the required view. They delegate to load() method.

  • remove() - removes a specified instance from the database. Delegates to commit() method.

While loading data, DataManager may also implement additional functionality described below.

Tip

See DataManager vs. EntityManager for information on differences between DataManager and EntityManager.