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

getItem() - возвращает экземпляр редактируемой сущности, установленный в главном источнике данных экрана (т.е. указанном в атрибуте datasource корневого элемента XML-дескриптора).

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

Изменения, вносимые в экземпляр, возвращаемый getItem(), отражаются на состоянии источника данных, и будут отправлены на Middleware при коммите экрана.

@Override
public void init(Map<String, Object> params) {
  Customer item = WindowParams.ITEM.getEntity(params);
  // do something
}

setItem() - вызывается фреймворком при открытии экрана методом openEditor() для установки редактируемого экземпляра сущности в главном источнике данных. В момент вызова созданы все компоненты и источники данных экрана, и отработал метод init() контроллера.

Для инициализации экрана редактирования вместо переопределения setItem() рекомендуется имплементировать специальные шаблонные методы initItem() и postInit().

initNewItem() - шаблонный метод, вызываемый фреймворком перед установкой редактируемого экземпляра сущности в главном источнике данных.

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

@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() - шаблонный метод, вызываемый фреймворком на финальной стадии коммита изменений. Параметры метода:

Реализация метода по умолчанию, если экран не закрывается, отображает сообщение об успешном коммите изменений и вызывает метод 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);
}