СОТРУДНИЧЕСТВО

Руководство по разработке

Практическое руководство по разработке приложений на фреймворке Melda: установка окружения и первый запуск, модель данных и её отображение на схему MySQL, меню, пользовательские компоненты, инъекции, формы и метаданные интерфейса, права доступа, фильтры, отладка и миграция схемы БД, сборка приложения. Примеры сверены с исходным кодом каркаса; места, где прежняя документация расходилась с реализацией, отмечены отдельно.

Быстрый старт

Приложение на Melda — это обычный Java-проект, который подключает библиотеку каркаса, описывает модель данных классами DataModel и передаёт управление фасаду Melda. Каркас создаёт схему базы данных, загружает метаданные интерфейса, строит окна и меню, проверяет права пользователя.

Требования к окружению

Таблица 1. Компоненты окружения
КомпонентНазначениеПримечание
JDK (Java SE)компиляция и запуск приложенияминимальная версия в исходниках не зафиксирована; код написан без модульной системы
JavaFXпользовательский интерфейсначиная с JDK 11 поставляется отдельно — SDK или зависимости проекта
RichTextFXредактор кода с подсветкойнужен только для компонента CodeEditor (тип code)
MySQLхранение данных и метаданных интерфейсаединственная поддерживаемая СУБД
MySQL Connector/JJDBC-драйвердолжен быть в classpath приложения
melda2vxlib.jarбиблиотека каркасаподключается к проекту как обычная библиотека
meldadb.sqlпрототип базы данныхсодержит системные таблицы bms_* и стартовое наполнение

Порядок подготовки проекта:

  1. Подключить к проекту библиотеку melda2vxlib.jar, JavaFX (модули javafx.controls, javafx.media, javafx.web) и RichTextFX.
  2. Развернуть прототип базы данных meldadb.sql в MySQL.
  3. Создать пользователя СУБД meldaroot и предоставить ему полные права на базу данных, включая CREATE и ALTER: каркас изменяет схему при миграции.
  4. Внести учётную запись meldaroot в таблицу bms_users.
  5. Создать структуру пакетов приложения и обязательные классы (см. ниже).
  6. Собрать проект и запустить стартовый класс.

Логин и пароль в bms_users должны совпадать с учётной записью MySQL. Авторизация в Melda выполняет запрос к bms_users, а затем тем же логином и паролем открывает JDBC-соединение с базой. Если пароль в bms_users.upass не совпадает с паролем пользователя СУБД, приложение не подключится к базе, даже если проверка в таблице прошла успешно.

Структура проекта

Базовый пакет приложения задаётся вызовом Melda.i().setAppPackage("app"). Каркас сканирует четыре подпакета этого пакета — components, injects, menu, models — и находит в них классы, помеченные аннотациями. Подпакеты внутри этих четырёх каталогов не сканируются: классы должны лежать непосредственно в указанных пакетах.

app
├── components          // пользовательские компоненты и их строители
├── injects             // классы инъекций
├── menu
│   └── USRMenuBuilder.java
├── models
│   ├── USRDataModelsInit.java
│   └── ...Model.java
└── res                 // ресурсы приложения (в тестовом проекте — main.png)

Пакет res содержит ресурсы, которые загружаются через classpath; в тестовом приложении там лежит main.png — изображение экрана авторизации.

Обязательные классы

Строитель меню. В пакете app.menu создаётся ровно один класс с аннотацией @MeldaMenuBuilder. Он наследует MenuBuilder и перегружает метод build().

package app.menu;

import MELDAVX.annotations.MeldaMenuBuilder;
import MELDAVX.windowmodel.menus.MenuBuilder;

@MeldaMenuBuilder
public class USRMenuBuilder extends MenuBuilder {

    @Override
    public void build() {
        addMenu("Тестовое меню");
        addMenuScreen("Тестовое меню", "Тестовый экран", "testScreen");
    }
}

Инициализация моделей данных. В пакете app.models создаётся ровно один класс с аннотацией @MeldaUserDMInit. Он наследует DataModelsInit, реализует DataModelInit и регистрирует списки методом listInit(...).

package app.models;

import MELDAVX.annotations.MeldaUserDMInit;
import MELDAVX.datamodelinit.DataModelInit;
import MELDAVX.datamodelinit.DataModelsInit;

@MeldaUserDMInit
public class USRDataModelsInit extends DataModelsInit implements DataModelInit {

    @Override
    public void init() {
        listInit(new TestDataModel(), "testdata", "default");
    }
}

Точка входа. Главный класс наследует javafx.application.Application, задаёт параметры каркаса в методе start(Stage) и вызывает Melda.i().init(stage).

package app;

import MELDAVX.Melda;
import MELDAVX.dbsyncs.DBSync;
import MELDAVX.dbsyncs.OptDB;
import javafx.application.Application;
import javafx.stage.Stage;

public class TestMain extends Application {

    @Override
    public void start(Stage stage) throws Exception {
        // Имя приложения выводится в заголовке окна и в сообщениях
        Melda.i().setAppName("Melda Test App");
        // Базовый пакет расширений: app.models, app.menu, app.injects, app.components
        Melda.i().setAppPackage("app");
        // Основной источник данных
        Melda.i().createDBSyncDefault("127.0.0.1", 3306, "meldabase", DBSync.typeMySQL);
        // Учётная запись: логин и пароль совпадают с записью в bms_users и с учёткой MySQL
        Melda.i().setUserAndPass("meldaroot", "пароль");

        // Отладочный режим и миграция схемы — только для разработки:
        // Melda.i().setOptDBDebugMode(true);
        // Melda.i().setOptMode(OptDB.optFullUpdate);

        // Запуск каркаса
        Melda.i().init(stage);
    }

    public static void main(String[] args) {
        launch(args);
    }
}

Стартовый класс. Для запуска удобно использовать отдельный класс FakeMain, который не наследует Application и просто передаёт управление главному классу. В тестовом проекте он импортирует app.TestMain.

package app;

import app.TestMain;

public class FakeMain {
    public static void main(String[] args) {
        TestMain.main(args);
    }
}

Первый запуск

  1. Собрать проект: библиотека каркаса, JavaFX, RichTextFX и драйвер MySQL должны попасть в classpath.
  2. Запустить app.FakeMain. При запуске приложение авторизуется по учётной записи, переданной в setUserAndPass.
  3. Убедиться, что в базе существуют системные таблицы bms_* и строка пользователя в bms_users. Если таблиц нет, включите отладочный режим с миграцией схемы (раздел 9).
  4. Открыть системное меню BMS Setup и создать экран, форму и правила доступа; пользовательские меню появятся после добавления правил (разделы 3, 6, 7).

Если проект создан из типового шаблона Melda, структура пакетов и обязательные классы уже готовы. В этом случае достаточно выполнить пункт 4 подготовки — внести пользователя в bms_users — и указать в TestMain адрес базы, имя базы и учётные данные.

Файлы для загрузки — библиотека melda2vxlib.jar, прототип meldadb.sql и PDF руководства — собраны в разделе «Загрузки».

1. Архитектура Melda-приложения

Любое приложение на базе Melda состоит из экранов с меню и компонентами, форм, моделей данных и инъекций компонентов. Ядро каркаса — библиотека melda2vxlib.jar; прикладной проект содержит только описание предметной области и расширения.

Экран, компоненты, модели и формы

  • Экран — базовый элемент интерфейса, содержащий компоненты: таблицы, списки, кнопки, надписи и т. д. Экран описывается строкой в bms_screens, его состав — строками в bms_scr_components.
  • Компоненты делятся на встроенные и пользовательские. Встроенные типы (ScreenLabel, ScreenButton, ListNavigator, TableNavigator, HListNavigator, ComboNavigator, CodeEditor, VideoViewer) добавляются на экран в конструкторе BMS Setup; поведение частично меняется инъекциями. Пользовательские компоненты разрабатываются в пакете app.components (раздел 4).
  • Модель данных — набор классов-наследников DataModel в пакете app.models. Каждый класс описывает структуру одного Melda-списка, а список соответствует ровно одной таблице БД. Типы полей в Melda и в MySQL могут различаться: каркас сам хранит и переводит значения.
  • Форма — специальный экран для ввода и изменения данных в списках. Форма состоит из групп и элементов, которые добавляются в конструкторе BMS Setup; изменения автоматически записываются в БД.
  • Меню — элемент главного окна; открывает экраны или (в перспективе) запускает методы-инъекции. Поддерживается не более двух уровней меню. Меню строится программно, а не из базы.
  • Инъекция — метод, обёрнутый в класс-наследник InjectMethod и привязанный к тройке «окно — компонент — событие». Классы инъекций размещаются в пакете app.injects (раздел 5).
Окно приложения на фреймворке Melda: панель вкладок, навигаторы и таблица курсов
Приложение на Melda: главное окно с вкладками, навигаторами и таблицей — состав экрана задан метаданными в базе, данные — моделью в коде.

Три модели и слои

Архитектурная особенность Melda — одновременное существование трёх моделей, описанных разными средствами и играющих разные роли.

Таблица 2. Три модели Melda
МодельГде описанаЧто определяет
Модель данныхтипизированный Java-код: наследники DataModel, поля DFBструктуру списков и их отображение на таблицы MySQL
Модель представленияшесть таблиц bms_screens, bms_scr_components, bms_forms, bms_form_groups, bms_form_elements, bms_filtersсостав экранов, формы, фильтры; меняется без пересборки приложения
Системная модельклассы DataModel пакета datamodelinit.defmodelsпользователей, группы, правила доступа и сами метаданные интерфейса

Слои каркаса: прикладной (DataModel, MenuBuilder, InjectMethod, ComponentBuilder), фасад (Melda, MeldaUI), модель данных (DataField, DataField-наследники, DataClass, DataList), персистентность (DBSync, DBSMySQL), миграция схемы (OptDB), интерфейс (Component, Window, навигаторы, формы, меню), доступ (MUser, MUserGroup, MAccessRule, MARuleChecker) и расширения (accessReflect, accessInjects, аннотации).

Порядок инициализации жёстко задан в Melda.init: авторизация → регистрация системных и пользовательских моделей → регистрация пользовательских строителей компонентов (обязательно до загрузки данных) → при отладке миграция схемы и выход → загрузка данных → пользователи и правила → инъекции → построение меню и окон. Нарушение порядка приводит к NullPointerException или к тому, что метаданные не отображаются на классы.

Подробное описание подсистем, классов и ограничений приведено на странице «Техническое описание».

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

Каждая таблица базы данных связана с классом-наследником DataModel — этот класс описывает структуру соответствующего Melda-списка. Классы моделей размещаются в пакете app.models; список регистрируется в USRDataModelsInit. Имена полей модели должны совпадать с именами колонок таблицы.

DataModel, DataClass, DataList

  • DataField — прототип поля: имя, заголовок, тип, строковое значение и флаг изменённости. Значение любого типа хранится строкой; разбор и преобразование к виду БД выполняют наследники.
  • DataModel наследует ArrayList<DataField> и представляет собой шаблон. Метод init() наполняет список прототипами полей; при создании записи каркас клонирует каждый прототип и обнуляет значение.
  • DataClass — запись: идентификатор id, набор полей и три флага состояния added, updated, removed. По этим флагам подсистема синхронизации решает, какие операции выполнять в БД. Флаг prototype отличает служебную запись-шаблон от сохранённой.
  • DataList — именованная коллекция записей, привязанная к источнику данных строкой dbSyncName. Имя списка совпадает с именем таблицы. Поиск записи выполняется линейным перебором по id.

Идентификаторы записей генерирует приложение (DataIdCounter), а не СУБД. Это значит, что таблицы Melda не требуют AUTO_INCREMENT, но и не защищают от конфликтов идентификаторов при внешних вставках.

Простые типы полей

Все поля создаются статической фабрикой DFB и добавляются в модель вызовом this.add(...). Один тип поля соответствует одному SQL-типу; отображение задаётся единственным методом DBSMySQL.getTypeOfDataField.

Таблица 3. Простые типы полей и их SQL-представление
ТипДобавлениеSQL-типОсобенности
DFStringDFB.dfString(имя, надпись, максСимволов)varchar(n) или tinytext/text/mediumtext/longtextположительное число символов → varchar(n); спецконстанты — текстовые типы; длина проверяется в setValue
DFBooleanDFB.dfBoolean(имя, надпись)varchar(1)в БД '0'/'1'; в записях — «да»/«нет» (см. примечание ниже)
DFIntegerDFB.dfInteger(имя, надпись)intgetIntValue/setIntValue, проверка числа при разборе
DFMoneyDFB.dfMoney(имя, надпись, валюта)intвалюта DFMoney.mRUB, mUSD, mEURO; значение хранится как float, но SQL-тип — int
DFDateDFB.dfDate(имя, надпись)dateзначение через TimeMoment; в интерфейсе дд.мм.гггг, в БД — гггг-м-д без ведущих нулей (MySQL нормализует дату при хранении)
DFTimeDFB.dfTime(имя, надпись)timeзначение через TimeMoment; полночь отображается как 23:59:59

DFString. Максимальное количество символов допускает как положительное число, так и специальные константы: charsCountTiny (−2, tinytext, до 255 символов), charsCountShort (−3, text, до 65 535), charsCountMedium (−4, mediumtext), charsCountLong (−5, longtext). Положительное число создаёт varchar(n) с проверкой длины. Значение -1 снимает ограничение длины в памяти, но SQL-тип для него не определён: при миграции схемы будет выведено сообщение об ошибке. Для больших текстов используйте константы charsCount*.

public class CourseCatsModel extends DataModel {
    @Override
    public void init() {
        this.add(DFB.dfString("name", "Имя категории", 100));
        this.add(DFB.dfString("title", "Надпись", 300));
        this.add(DFB.dfString("descshort", "Краткое описание", DFString.charsCountTiny));
        this.add(DFB.dfString("desclong", "Полное описание", DFString.charsCountMedium));
    }
}

DFBoolean. В загруженных и склонированных записях значение поля — строка «да» или «нет»; в базу данных каркас записывает '1' или '0' (столбец varchar(1)). Метод setValue понимает только строки '1' и '0' (пустая строка трактуется как «нет»), а getBoolValue возвращает true только для «да». В прикладном коде используйте setValue("1") или setValue("0"): метод setBoolValue(boolean) записывает в значение '1'/'0', и getDBStringValue для такого значения вернёт null.

DFMoney. Поддерживаются валюты DFMoney.mRUB (рубли), DFMoney.mUSD (доллары), DFMoney.mEURO (евро). Валюта влияет только на отображаемый суффикс («руб», «$», «eu»); SQL-тип поля — int, поэтому дробная часть суммы в БД не сохраняется. Для денежных сумм с копейками текущая реализация не подходит.

DFDate и DFTime. Оба типа хранят значение в объекте TimeMoment. DFDate.setValue ожидает строку БД в формате гггг-мм-дд, DFTime — чч:мм:сс. Для времени есть особенность: значение 00:00:00 метод getStringTime показывает как 23:59:59, а строка 23:59:59 разбирается обратно в полночь. Не используйте это значение как служебный маркер.

Специальные типы полей

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

DFData — ссылка на запись другого списка. Добавляется методом DFB.dfData(имя, надпись, имяСписка). В БД хранится id связанной записи (int), отсутствие ссылки — -1. Поля связанной записи, которые показываются в таблицах и формах, задаются сразу после добавления поля вызовом DFB.addShowedFields(имяПоля) — метод можно вызывать несколько раз.

public class CoursesModel extends DataModel {
    @Override
    public void init() {
        this.add(DFB.dfString("coursename", "Имя курса", 200));
        this.add(DFB.dfData("coursecat", "Категория", "coursecats"));
        DFB.addShowedFields("title");
    }
}

Список-источник должен быть зарегистрирован раньше модели, которая на него ссылается: DFB.dfData ищет список в реестре в момент выполнения init(). Если список ещё не создан, метод выведет сообщение об ошибке и вернёт null. Поэтому в USRDataModelsInit сначала регистрируются справочники, затем — зависимые списки. Поиск выполняется только по источнику default.

DFFile — файл. Правильное добавление — DFB.dfFile(имя, надпись, имяХоста); в качестве хоста указывается значение поля fhostname из таблицы bms_remote_hosts либо ключевое слово localhost для выбора файла на локальных носителях. Каталог выбора задаётся методом DFB.setFilePath(...), расширения — повторными вызовами DFB.addFileExt(...). Если расширения не добавлены, выбирается файл любого расширения. Метод DFB.setFileValueWithPath(boolean) включает режим, при котором в значении поля хранится и путь, и имя файла; в БД записывается склейка пути и значения.

this.add(DFB.dfFile("imagesmall", "Маленький рисунок", "mtClientHost"));
DFB.setFilePath("/imagescourses/");
DFB.setFileValueWithPath(true);
DFB.addFileExt("png");
DFB.addFileExt("jpg");
DFB.addFileExt("jpeg");
DFB.addFileExt("gif");

Выбора файлов в интерфейсе текущей версии нет. Перечисленные методы (setFilePath, addFileExt, setFileValueWithPath) только сохраняют настройки в метаданных поля; ни один встроенный компонент или элемент формы их не использует, диалога выбора файла нет. Значение поля задаётся программно либо вручную текстом пути. Ключевое слово localhost отдельно не обрабатывается: в качестве хоста передаётся значение fhostname из bms_remote_hosts, а пустое значение или default означает удалённый хост по умолчанию.

DFChoice — выбор из справочника значений. Добавляется методом DFB.dfChoice(имя, надпись, максСимволов); пары «ключ — отображаемое значение» добавляются вызовами DFB.addChoiceValues(ключ, значение). В памяти поле хранит ключ, а в базу данных записывается отображаемое значение; при загрузке каркас выполняет обратное преобразование. Это важно при ручном заполнении таблиц: в колонке окажется подпись, а не ключ.

this.add(DFB.dfChoice("status", "Статус", 20));
DFB.addChoiceValues("active", "Активен");
DFB.addChoiceValues("archive", "В архиве");

DFHashtegs — набор меток. Добавляется методом DFB.dfHashTegs(имя, надпись, списокМеток, имяПоляМетки); в отличие от других фабрик, третьим аргументом передаётся не имя, а объект DataList справочника меток. Значение разбирается на метки вида #метка и проверяется по справочнику; в БД хранится строка меток через пробел (text). Список меток должен быть зарегистрирован до модели.

DataList hashtegs = accessDataRegistry.i().getDataList("hashtegs");
this.add(DFB.dfHashTegs("tags", "Метки", hashtegs, "tag"));

DFURL — ссылка. Добавляется методом DFB.dfURL(имя, надпись, типСсылки). Допустимые типы: DFURL.linkUndefined (0), linkHTTPURL (1), linkFTPURL (2), linkMAILTO (3), linkWHATSAPP (4), linkTELEGRAM (5). Значение хранится строкой в varchar(300) и разбирается на протокол, сайт и документ. Проверка протокола в текущей версии ослаблена, поэтому полагаться на неё как на валидацию нельзя.

DFTel — телефон. Добавляется методом DFB.dfTel(имя, надпись), хранится в varchar(20). Собственной логики проверки у типа нет.

DFMultidata — множественная ссылка (заготовка). Фабрика DFB.dfMultiData(имя, надпись, имяСписка) существует, но класс не задаёт собственный тип поля: наследуется typeBool, поэтому колонка создаётся как varchar(1), а разбор строки в setValue не выдерживает некорректных значений. Использовать тип в прикладном коде не следует: в текущей версии он неработоспособен.

DFPoint — точка (заготовка). У класса нет фабрики в DFB, не задан тип поля и не реализованы значение и клонирование. Добавить точку в модель через DFB невозможно; тип оставлен на будущее.

Инициализация списков

После создания модели список нужно зарегистрировать. Это делается в USRDataModelsInit методами DataModelsInit:

Таблица 4. Методы регистрации списков
МетодНазначение
listInit(dm, listName, dbSyncName)обычный список
listInitUsered(dm, listName, dbSyncName)список с владельцем записи: каркас поддерживает колонку meldauser
listInitCrypto(dm, listName, cryptoKey, dbSyncName)список с собственным ключом шифрования строковых полей
listInitUseredCrypto(dm, listName, cryptoKey, dbSyncName)список с владельцем записи и ключом шифрования

Параметры: dm — объект модели списка, listName — имя списка, совпадающее с именем таблицы, dbSyncName — имя источника данных; главный источник всегда default.

@MeldaUserDMInit
public class USRDataModelsInit extends DataModelsInit implements DataModelInit {

    @Override
    public void init() {
        // Справочники регистрируются до зависимых списков
        listInit(new LandsModel(), "lands", "default");
        listInit(new RegionsModel(), "regions", "default");
        listInit(new CitiesModel(), "cities", "default");
        listInit(new UsersModel(), "users", "default");
    }
}

Особенности listInitUsered. При включении режима usered каркас пишет в таблицу колонку meldauser, но автоматическое создание таблицы эту колонку не добавляет. Если таблица создаётся миграцией, добавьте колонку вручную: ALTER TABLE имя ADD COLUMN meldauser int(10); Иначе вставка и обновление записей будут падать. Фильтрации строк по текущему пользователю в текущей версии нет — usered только хранит владельца.

Шифрование строк. listInitCrypto задаёт ключ списка, но само поле нужно пометить вручную: DFB не имеет метода для этого. После создания поля приведите его к DFString и вызовите setEncrypted(true). По умолчанию ни одно системное поле не шифруется; алгоритм и ключи описаны в техническом описании.

Схема БД может создаваться автоматически по модели — этой возможностью управляет OptDB (раздел 9). В обычном режиме запуска каркас только читает данные и не меняет схему.

4. Пользовательские компоненты

Помимо встроенных компонентов, которые добавляются на экран и настраиваются в конструкторе BMS Setup, разработчик может создать собственный компонент и использовать его как ещё один тип в bms_scr_components.type. Компонент и его строитель размещаются в пакете app.components.

Базовый класс и конструктор

Все компоненты наследуют MELDAVX.windowmodel.components.Component. Компоненты, отображающие наборы данных, наследуют NavigatorComponent, который расширяет базовый класс источником данных, выбранными полями, заголовком и фильтрами. Наследоваться можно и от конкретного встроенного компонента.

Конструктор NavigatorComponent принимает шесть параметров:

NavigatorComponent(String name,
                   Component sourceComponent,
                   DataList dataSource,
                   ArrayList<String> selectedFields,
                   String title,
                   int align)
Таблица 6. Параметры конструктора NavigatorComponent
ПараметрНазначение
nameимя компонента из BMS Setup; по нему компонент находится в дереве и к нему привязываются инъекции
sourceComponentродительский компонент, обычно корневой компонент экрана; передаётся каркасом
dataSourceMelda-список, данные которого отображает компонент; берётся из поля linkedlist
selectedFieldsвыбранные поля источника данных; в BMS Setup задаются шаблоном в поле options
titleнадпись компонента из поля title
alignкод расположения на экране; полностью управляется Melda

Жизненный цикл компонента

  • buildPane() — создаёт визуальное представление компонента и обязана заполнить защищённое поле pane (JavaFX Pane). Вызывается из конструктора компонента; без неё каркас не сможет разместить компонент на экране.
  • update() — вызывается при обновлении контента: после изменения данных, выбора строки, обновления коллектора окон. Здесь компонент перечитывает данные из dataSource и обновляет свои контролы. Чтобы сохранить штатное поведение каркаса (обновление дочерних компонентов и инъекцию onUpdate), в конце метода вызывайте super.update().
  • updateElements() — вспомогательный хук для обновления внутренних элементов; встроенные компоненты вызывают его в конце update().
  • pane — защищённое поле базового класса; панель, которая вставляется в родительский компонент.
  • signalUpdate() — сообщает окну, что данные изменились, и запускает каскадное обновление.

Пример компонента, который показывает заголовок и количество записей источника:

package app.components;

import java.util.ArrayList;

import MELDAVX.datamodel.DataList;
import MELDAVX.windowmodel.components.Component;
import MELDAVX.windowmodel.components.navigators.NavigatorComponent;
import javafx.scene.control.Label;
import javafx.scene.layout.BorderPane;
import javafx.scene.layout.VBox;

public class SMEditorComponent extends NavigatorComponent {

    private Label lblTitle;
    private VBox box;

    public SMEditorComponent(String name, Component sourceComponent, DataList dataSource,
                             ArrayList<String> selectedFields, String title, int align) {
        super(name, sourceComponent, dataSource, selectedFields, title, align);
        buildPane();
    }

    @Override
    protected void buildPane() {
        pane = new BorderPane();
        box = new VBox();
        lblTitle = new Label(title);
        box.getChildren().addAll(lblTitle);
        ((BorderPane) pane).setCenter(box);
    }

    @Override
    public void update() {
        int count = (dataSource == null) ? 0 : dataSource.size();
        lblTitle.setText(title + " — записей: " + count);
        updateElements();
        super.update();
    }

    @Override
    public void updateElements() {
        // обновление внутренних контролов, если требуется
    }
}

Класс-строитель

Компонент создаётся не самим каркасом, а классом-строителем — наследником ComponentBuilder с аннотацией @MeldaUserComponentBuilder. Строитель читает строку метаданных компонента и возвращает экземпляр компонента.

package app.components;

import MELDAVX.annotations.MeldaUserComponentBuilder;
import MELDAVX.datamodel.DataClass;
import MELDAVX.datamodel.DataList;
import MELDAVX.datamodel.accessDataRegistry;
import MELDAVX.windowmodel.componentbuilders.ComponentBuilder;
import MELDAVX.windowmodel.components.Component;
import MELDAVX.windowmodel.windows.Window;

@MeldaUserComponentBuilder
public class SMEditorBuilder extends ComponentBuilder {

    @Override
    public Component buildComponent(DataClass dc, Window screenWindow, Component sourceComponent) {
        String name = dc.getDataField("name").getValue();
        String title = dc.getDataField("title").getValue();
        int align = Integer.valueOf(dc.getDataField("align").getDBStringValue());
        DataList dataSource = accessDataRegistry.i().getDataList(dc.getDataField("linkedlist").getValue());
        return new SMEditorComponent(name, sourceComponent, dataSource, null, title, align);
    }
}

Метод buildComponent получает строку bms_scr_components (dc), окно экрана и родительский компонент. Строитель сам решает, какие поля метаданных ему нужны: имя, заголовок, выравнивание, источник данных, шаблон из options, связанная форма. Выбранные поля можно разобрать из строки options по тому же принципу, что и во встроенных навигаторах, — например, извлекая имена из квадратных скобок.

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

Регистрация типа

Регистрация выполняется автоматически. При запуске accessReflect перечисляет классы пакета app.components, отбирает те, у которых первая аннотация — @MeldaUserComponentBuilder, создаёт строителей и складывает их в карту accessUserComponentBuilders. Ключом карты служит полное имя класса строителя.

Одновременно каркас добавляет пользовательские типы в список значений поля type таблицы bms_scr_components: ключ — полное имя класса строителя (оно отображается в комбобоксе формы Screens), значение — короткий код не длиннее 10 символов. Код строится автоматически из простого имени класса: отбрасываются суффиксы Builder и Component, остаток обрезается до 10 символов, при совпадении добавляется числовой суффикс. Например, для app.components.SMEditorBuilder код будет SMEditor.

Таблица 7. Где хранится тип пользовательского компонента
МестоЗначение
комбобокс в BMS Setupполное имя класса строителя, например app.components.SMEditorBuilder
колонка bms_scr_components.typeкороткий код, например SMEditor (varchar 10)
память при загрузкекод преобразуется обратно в полное имя класса; по нему ScreenWindowBuilder находит строителя

Регистрация строителей выполняется до загрузки данных: иначе строки bms_scr_components с пользовательским типом не отобразятся на класс, значение типа останется пустым, и при построении экрана возникнет NullPointerException. Если строки таблицы заполняются вручную, в колонке type указывайте именно сгенерированный код, а не имя класса.

Если пользовательский тип не появился в форме Screens, проверьте: базовый пакет задан вызовом setAppPackage("app"); класс строителя лежит непосредственно в app.components, а не в подпакете; аннотация стоит первой; у строителя есть публичный конструктор без параметров.

5. Инъекции

Инъекция — это класс-наследник InjectMethod, который каркас вызывает при наступлении события у компонента. Инъекции позволяют менять поведение уже построенных экранов, не наследуя и не переписывая их классы. Все классы инъекций размещаются непосредственно в пакете app.injects и помечаются аннотацией @MeldaInjectMethod.

Класс инъекции и привязка

Инъекция привязывается к тройке «окно — компонент — событие». Привязка задаётся в конструкторе: сначала вызывается конструктор базового класса с именем метода, затем устанавливаются имена окна, компонента и события.

package app.injects;

import java.util.ArrayList;

import MELDAVX.annotations.MeldaInjectMethod;
import MELDAVX.datamodel.accessDataRegistry;
import MELDAVX.windowmodel.components.InjectMethod;

@MeldaInjectMethod
public class InjDataSync extends InjectMethod {

    public InjDataSync() {
        // Требование Java: вызов super(...) должен быть первым оператором конструктора
        super("dataSync");
        setWindowName("testScreen");          // имя экрана из bms_screens.name
        setComponentName("syncButton");       // имя компонента из bms_scr_components.name
        setEventName("onClick");              // одно из событий Melda
    }

    @Override
    public void callMethod(Object onObject, ArrayList<Object> pars) {
        accessDataRegistry.i().getDbSync("default").updateData();
        MELDAVX.Melda.i().getMeldaUI().getCollector().update();
    }
}
  • Имя окна. Для экрана это значение bms_screens.name; именно оно становится именем окна при построении. Для окна формы имя окна — имя формы.
  • Имя компонента. Значение bms_scr_components.name. Для формы компонентом является сама форма, поэтому имя окна и компонента совпадают с именем формы.
  • Имя события. Одна из фиксированных строк: onUpdate, onClick, onSelectRow, colorRow.
  • Имя метода (первый аргумент super) в текущей версии в сопоставлении не участвует: accessInjects сравнивает только окно, компонент и событие. Имя сохранено для совместимости и будущего механизма меню-инъекций.

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

События и параметры

Таблица 8. События инъекций
СобытиеКомпонентыПараметры parsКогда вызывается
onUpdateкомпоненты на базе Component (в том числе ScreenButton), ScreenLabel, TableNavigator, контейнер экранаnullпри каскадном обновлении окна
onClickScreenButton, ScreenLabelnullпо клику мышью
onSelectRowTableNavigator, ListNavigator, ComboNavigatorpars.get(0) — NavigatorRowпри выборе строки или элемента
colorRowTableNavigatorpars.get(0) — NavigatorRowпри перерисовке каждой строки таблицы

В методе callMethod(Object onObject, ArrayList<Object> pars) первый аргумент — сам компонент, для которого сработало событие (не запись данных). Строка данных доступна только через pars для событий onSelectRow и colorRow. Для остальных событий pars равно null — не разыменовывайте его без проверки.

Событие onUpdate в текущей версии не возникает у ListNavigator, ComboNavigator и HListNavigator: их методы update() не вызывают инъекцию (в отличие от TableNavigator). Если нужно обновлять такой компонент по сигналу, используйте событие выбора строки или пересоздайте экран.

Рабочие примеры

onUpdate: обновление надписи по данным списка. Инъекция привязывается к компоненту ScreenLabel с именем titleLabel на экране testScreen.

package app.injects;

import java.util.ArrayList;

import MELDAVX.annotations.MeldaInjectMethod;
import MELDAVX.datamodel.accessDataRegistry;
import MELDAVX.windowmodel.components.InjectMethod;
import MELDAVX.windowmodel.components.ScreenLabel;

@MeldaInjectMethod
public class InjTitleCount extends InjectMethod {

    public InjTitleCount() {
        super("refreshTitle");
        setWindowName("testScreen");
        setComponentName("titleLabel");
        setEventName("onUpdate");
    }

    @Override
    public void callMethod(Object onObject, ArrayList<Object> pars) {
        ScreenLabel label = (ScreenLabel) onObject;
        int count = accessDataRegistry.i().getDataList("testdata").size();
        label.setTitle("Записей в списке: " + count);
    }
}

onClick: добавление записи из кнопки. Кнопка типа ScreenButton с именем addButton добавляет запись в список testdata, сохраняет её и обновляет окна.

package app.injects;

import java.util.ArrayList;

import MELDAVX.Melda;
import MELDAVX.annotations.MeldaInjectMethod;
import MELDAVX.datamodel.DataClass;
import MELDAVX.datamodel.DataList;
import MELDAVX.datamodel.accessDataRegistry;
import MELDAVX.windowmodel.components.InjectMethod;

@MeldaInjectMethod
public class InjAddRecord extends InjectMethod {

    public InjAddRecord() {
        super("addRecord");
        setWindowName("testScreen");
        setComponentName("addButton");
        setEventName("onClick");
    }

    @Override
    public void callMethod(Object onObject, ArrayList<Object> pars) {
        DataList list = accessDataRegistry.i().getDataList("testdata");
        if (list == null) return;

        DataClass dc = new DataClass(list);
        dc.setPrototype(false);
        dc.setSourceList(list);
        dc.getDataField("channelname").setValue("Новый канал");
        dc.getDataField("description").setValue("Добавлено из инъекции");
        dc.setAdded(true);

        list.add(dc);
        accessDataRegistry.i().updateData(list);
        Melda.i().getMeldaUI().getCollector().update();
    }
}

onSelectRow: реакция на выбор строки. Строка приходит в pars.get(0); через неё доступна исходная запись.

@Override
public void callMethod(Object onObject, ArrayList<Object> pars) {
    if ((pars == null) || pars.isEmpty()) return;
    NavigatorRow row = (NavigatorRow) pars.get(0);
    DataClass selected = row.getSourceData();
    System.out.println("Выбрана запись id = " + selected.getId());
    for (DataField df : selected.getDataFields()) {
        System.out.println(df.getTitle() + ": " + df.getValue());
    }
}

colorRow: подсветка строк таблицы. Метод вызывается для каждой строки перед её добавлением в таблицу, поэтому цвета применяются сразу.

@Override
public void callMethod(Object onObject, ArrayList<Object> pars) {
    if ((pars == null) || pars.isEmpty()) return;
    NavigatorRow row = (NavigatorRow) pars.get(0);
    String active = row.getSourceData().getDataField("active").getDBStringValue();
    if ("1".equals(active)) {
        row.setBackcolorCSS("#E8F5E9");
        row.setFontcolorCSS("#1B5E20");
        row.setColored(true);
    }
}

Событие colorRow есть только у TableNavigator; списки, выпадающие списки и иерархические навигаторы его не вызывают.

6. Формы и конструктор BMS Setup

Формы и экраны — это метаданные, а не код. Пользователь meldaroot редактирует их в системном меню BMS Setup, которое содержит экраны Forms (формы, группы и элементы), Screens (экраны и компоненты) и Users and rules (пользователи, группы, правила). Содержимое этих экранов хранится в таблицах bms_*; изменения вступают в силу после перезапуска приложения.

Форма приложения на фреймворке Melda: группы полей и элементы ввода
Форма Melda: группы полей и элементы ввода собраны по строкам bms_forms, bms_form_groups и bms_form_elements.

Таблицы форм

Таблица 9. Метаданные форм
ТаблицаПоляНазначение
bms_formsname (100), title (200), type (1), linkedlist (50)форма: имя, заголовок, тип и список-источник
bms_form_groupsform (ссылка на форму), title (100), align (1)группа полей формы
bms_form_elementsformg (ссылка на группу), type (2), label (100), fieldname (20), defvalue (50), size (int), viewtype (1), options (500)элемент формы: тип, надпись и поле модели
  • bms_forms.type: BaseForm = 1, MultiForm = 2. В текущей версии значение не читается: всегда строится BaseForm, мультиформы не реализованы.
  • bms_forms.linkedlist — объявлено как имя списка-источника, но текущий FormWindowBuilder его не читает: список форма получает от навигатора, из которого открывается (его linkedlist). Заполняйте поле для совместимости с метаданными, но полагаться на него нельзя.
  • bms_form_groups.align: Vertical = 1, Horisontal = 2.
  • bms_form_elements.fieldname — имя поля модели; оно должно совпадать с именем, заданным в DataModel. При несовпадении элемент не построится корректно.
  • Поля defvalue, size и options в текущей версии строителем форм не читаются; viewtype читается только для DataChecker.

Элементы форм

Таблица 10. Типы элементов формы
ТипКодРеализация
BooleanChecker1выпадающий список «Да/Нет» для поля DFBoolean
ChoiceChecker2выпадающий список значений поля DFChoice
DataChecker3выбор связанной записи через диалог; поддерживается viewtype = 1
DateChecker4день, месяц, год и кнопка календаря (класс DateCheker)
MultiDateChecker5не реализован: обращение к несозданной мультиформе приводит к NullPointerException
TextInput6однострочное поле ввода с проверкой длины поля
TimeInput7ввод часов, минут и секунд
BigTextInput8многострочное поле ввода
PathChecker9объявлен в справочнике, но не реализован: элемент молча пропускается
MultiDataChecker10объявлен в справочнике, но не реализован: элемент молча пропускается
Таблица 11. Тип отображения элемента (viewtype)
ЗначениеКодПрименение
Standard1единственный реализованный вариант для DataChecker
Minimal2объявлен, для DataChecker не реализован
Middle3объявлен, для DataChecker не реализован
Extended4объявлен, для DataChecker не реализован

Централизованной валидации у элементов формы нет: проверки выполняются точечно внутри элементов, сообщения об ошибках не предусмотрены. Отмена редактирования не требует отката: форма работает с копией полей, а запись изменяется только по нажатию «Добавить» или «Изменить».

Экраны и компоненты

Таблица 12. Метаданные экранов
ТаблицаПоляНазначение
bms_screensname (50), title (200)экран: идентификатор и заголовок вкладки
bms_scr_componentsname (50), screen, type (10), title (200), linkedlist (50), align (2), options (200), linkedformкомпонент экрана: тип, источник данных, выравнивание, шаблон и связанная форма

Поле type — это выбор из справочника. В комбобоксе отображается полное имя, в БД хранится короткий код. Встроенные значения:

Таблица 13. Типы компонентов экрана
ТипКод в БДВизуализация
ScreenLabelscrlblнадпись; клик вызывает onClick
ScreenButtonscrbtnкнопка; клик вызывает onClick
ListNavigatorlstnavсписок ListView; шаблон строки в options
TableNavigatortabnavтаблица TableView; колонки по выбранным полям
HListNavigatorhlnavдерево TreeView; иерархия по полю-родителю
ComboNavigatorcmbnavвыпадающий список ComboBox
CodeEditorcodeредактор кода RichTextFX; в options — два поля: заголовок и содержимое
VideoViewervidvwпроигрыватель JavaFX Media; в options нужны два поля (иначе ошибка), но сам компонент ожидает в списке поля path и file1080p
Calendarcalобъявлен в справочнике, но строителя нет — при выборе будет NullPointerException
ReviewViewrevvwобъявлен в справочнике, но строителя нет — при выборе будет NullPointerException

Шаблон options задаёт выбранные поля в квадратных скобках: для таблицы — [coursename] [title], для списка — [coursename]; для иерархического навигатора шаблон имеет вид <coursecats>{path}[title], где <coursecats> — необязательное имя списка, {path} — поле пути, далее шаблон строки.

Таблица 14. Коды выравнивания компонента (align)
КодЗначение справочникаФактическое размещение
1FullCenterцентр экрана; несколько компонентов с кодом 1 перекрывают друг друга
2VBoxLeftлевая колонка
3VBoxRightправая колонка
4VBoxFullобъявлен, но при размещении не используется
5HBoxTopобъявлен, но при размещении не используется
6HBoxBottomобъявлен, но при размещении не используется
7VBoxCenterцентральная колонка

Связанная форма (linkedform) используется навигаторами: по ней строятся окна создания и изменения записи. Если форма не указана, навигатор работает только на просмотр. Источник данных (linkedlist) — имя зарегистрированного Melda-списка.

Пошаговый рецепт

Типовой порядок добавления новой сущности в приложение:

  1. Модель и список. Создать класс-наследник DataModel в app.models, описать поля через DFB и зарегистрировать список в USRDataModelsInit методом listInit(...). При необходимости создать таблицу в БД через отладочный режим OptDB (раздел 9).
  2. Форма. В BMS Setup → Forms создать форму: name, title. Поле linkedlist у формы в текущей версии не читается — список форма получает от навигатора, поэтому связанная форма должна открываться из навигатора с правильным linkedlist. Добавить группы (заголовок и выравнивание) и элементы: тип, надпись, fieldname из модели. Для ссылочного поля — DataChecker со viewtype = 1.
  3. Экран. В BMS Setup → Screens создать экран (name, title), затем компоненты: навигатор с linkedlist, шаблоном options, связанной формой linkedform; при необходимости — надписи и кнопки.
  4. Меню. В USRMenuBuilder добавить пункт: addMenuScreen("Родитель", "Пункт", "имяЭкрана"). Родительское меню должно быть добавлено раньше пункта.
  5. Права. В BMS Setup → Users and rules выдать текущей группе или пользователю правило с allowvmenu для родительского меню и пункта, а также правило с allowvscreen для экрана. Без правил пункт не отображается.
  6. Перезапуск. Метаданные и меню читаются при запуске; после изменений перезапустить приложение и проверить экран, форму и права.

Если после создания экрана при открытии возникает NullPointerException без сообщения, проверьте три вещи: имя экрана в addMenuScreen совпадает с bms_screens.name; у каждого компонента тип имеет строителя; linkedlist указывает на зарегистрированный список.

7. Пользователи, группы и права доступа

Авторизация выполняется по таблице bms_users: при запуске каркас запрашивает строку с логином и паролем и тем же логином и паролем открывает соединение с MySQL. После загрузки данных пользователи, группы и правила читаются в память; проверка прав выполняется при построении меню и при открытии экрана.

Пользователи и группы

Таблица 15. Пользователи, группы и правила
ТаблицаПоляНазначение
bms_usersulogin (50), upass (50), uname (100), usecname (100), usurname (100), position (100), ugroup (ссылка на группу)учётные записи; логин и пароль одновременно служат учётными данными MySQL
bms_user_groupsgname (200)группы пользователей
bms_access_rulesmgroup (ссылка на группу), muser (ссылка на пользователя), allowvmenu (100), allowvscreen (ссылка на экран)белые списки: разрешение меню и экрана для группы или пользователя
bms_access_list_rulesmgroup, muser, dlistname, allowview, allowadd, allowchangeобъявлена, но не используется ни одной проверкой
bms_user_subordinatesmuser (руководитель), msubuser (подчинённый)объявлена, в текущей версии не используется

Учётная запись meldaroot должна быть внесена в bms_users и привязана к группе. Ей, как правило, выдан доступ к системному меню BMS Setup. Если поле ugroup пусто, при загрузке пользователей возникает NullPointerException: класс MUserGroup строится из ссылки на группу без проверки на null. Та же ошибка возникнет при проверке прав, если группа не загружена.

Правила доступа

Правило MAccessRule содержит ровно два атрибута: allowViewMenu (строка — заголовок меню или пункта) и allowViewScreen (ссылка на запись экрана). Проверка устроена как белый список с приоритетом групповых правил:

  1. Если разрешение найдено в правилах группы текущего пользователя, доступ разрешается.
  2. Иначе проверяются личные правила пользователя.
  3. Если разрешения нет ни там, ни там, доступ запрещён.

Меню и экран проверяются отдельно: для отображения пункта нужно правило allowvmenu с точным заголовком пункта, а для открытия экрана — правило allowvscreen с нужным экраном. Родительское меню также требует собственного правила; без него дочерние пункты не строятся.

Прав на данные нет. Механизм разграничивает только меню и экраны; прав на списки, записи, поля и операции (чтение, добавление, изменение, удаление) в текущей версии не существует. Таблица bms_access_list_rules объявлена, но не участвует в проверках. Для ролевой модели, различающей, например, администратора, преподавателя и обучающегося по данным, механизма недостаточно — такие ограничения реализуются прикладным кодом.

Правила и группы читаются при запуске; после изменения таблиц в BMS Setup → Users and rules приложение нужно перезапустить. Пароль хранится в открытом виде и совпадает с паролем MySQL — это ограничение текущей реализации (раздел 11).

8. Фильтры и переменные

Фильтры ограничивают набор записей, отображаемых навигатором или полем выбора формы. Они хранятся в таблице bms_filters и читаются при построении экрана или открытии формы; изменение фильтров требует перезапуска приложения.

Таблица bms_filters

Таблица 16. Поля фильтра
ПолеТипНазначение
scrnavссылка на bms_scr_componentsкомпонент экрана, к которому применяется фильтр
formcompссылка на bms_form_elementsэлемент формы, к которому применяется фильтр (для поля выбора)
fieldvarchar(20)имя поля источника данных
relationвыбор: ==, !=, cnотношение: равно, не равно, содержит
expressionvarchar(100)выражение: литерал, переменная или data-команда
defbooleanобъявлено как «По умолчанию», но в коде не читается
logictypeвыбор: AND = 0, OR = 1логика объединения с предыдущими фильтрами

Для навигатора фильтр применяется к каждой записи списка до построения строк. Сравнение идёт по строковому значению поля для БД: для DFData это идентификатор связанной записи, для DFBoolean — '0'/'1'. Поле id сравнивается как число. Для ссылочного поля отсутствие ссылки соответствует строке none.

Фильтры формы (formcomp) действуют только для элемента DataChecker и поддерживают отношения == и !=; отношение cn в форме не обрабатывается.

Переменные $ и #

  • $имя — переменная окна. Для каждого навигатора экрана каркас автоматически создаёт переменную с именем компонента и начальным значением -1; при выборе строки в неё записывается id выбранной записи. Переменная доступна фильтрам других компонентов того же окна.
  • #имя — переменная коллектора окон, общая для всего сеанса. Каркас создаёт её, например, для WebViewer (имя browser); прикладной код может создать свою через accessVars.i().createNewVar(collector, имя, значение).
  • имяСписка.getDC(id).getDF(поле) — data-команда: получить запись списка по идентификатору и значение её поля. Аргументы могут быть литералами или переменными $/#. Например, courses.getDC($coursesnav).getDF(title) вернёт название курса, выбранного в навигаторе coursesnav.

Выражение фильтра разбирается так: если оно содержит точку, оно считается data-командой; иначе если начинается с $ или # — это переменная; иначе — литерал. Если переменная не найдена, выражение становится пустым.

Мастер-деталь

Связь «мастер — деталь» строится без прямых ссылок между компонентами, через переменную окна. На экране размещаются два навигатора: catnav по списку coursecats и coursesnav по списку courses. При выборе категории в переменную $catnav записывается её id, а фильтр второго навигатора подставляет эту переменную.

Таблица 17. Пример строки bms_filters для связи «мастер — деталь»
ПолеЗначение
scrnavкомпонент coursesnav
fieldcoursecat
relation==
expression$catnav
logictypeAND

Пока категория не выбрана, переменная равна -1, и второй навигатор не показывает записей. После выбора строки каркас обновляет окно, и детали перестраиваются. Фильтры можно комбинировать: несколько строк с logictype = AND/OR объединяются последовательно, первый фильтр применяется к полному набору записей.

9. Отладка и миграция схемы БД

Melda умеет приводить схему базы данных к модели: создавать отсутствующие таблицы и колонки, изменять типы колонок. Эта операция выполняется только в отладочном режиме optDBDebugMode — в обычном запуске каркас схему не меняет.

Режимы OptDB

Таблица 18. Режимы работы OptDB
КонстантаЗначениеПоведение
OptDB.optOnlyCheck1только диагностика: схема не изменяется; режим по умолчанию
OptDB.optCreateTables2создание отсутствующих таблиц; колонки не добавляются и не изменяются
OptDB.optFullUpdate3создание таблиц и колонок, изменение типов существующих колонок
OptDB.optShowDataLists4диагностическая печать содержимого списков; схема не изменяется

Включение режима

Режим включается в методе start главного класса до вызова Melda.i().init(stage). Обратите внимание на правильные значения: в прежней документации было указано setOptDBDebugMode(false), что отключало режим.

public class TestMain extends Application {

    @Override
    public void start(Stage stage) throws Exception {
        Melda.i().setAppName("Melda Test App");
        Melda.i().setAppPackage("app");
        Melda.i().createDBSyncDefault("127.0.0.1", 3306, "meldabase", DBSync.typeMySQL);
        Melda.i().setUserAndPass("meldaroot", "пароль");

        // 1. Включаем отладочный режим
        Melda.i().setOptDBDebugMode(true);
        // 2. При необходимости включаем полное обновление схемы
        Melda.i().setOptMode(OptDB.optFullUpdate);

        Melda.i().init(stage);
    }
}

В отладочном режиме графический интерфейс не открывается: после инициализации моделей каркас выполняет OptDB.checkDB() и завершает запуск. Отчёт выводится в консоль. Чтобы режим сработал, авторизация должна пройти успешно — учётная запись передаётся в setUserAndPass до init. Режим optMode действует только вместе с optDBDebugMode(true): без отладочного флага checkDB не вызывается.

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

Melda opt: Debug mode started.
Melda opt: FULL UPDATE MODE ACTIVE!!!
Melda opt: db table testdata was builded in DBS: default
Melda opt: all tables was builded.
Melda opt: all fields was checked.
Melda opt: Debug mode finished. Remove opt flag to start app.

Если включён только optDBDebugMode без optFullUpdate, выполняется проверка: в консоль выводятся отсутствующие таблицы, отсутствующие и лишние колонки, несовпадения типов, но схема не изменяется.

Что создаётся и чего нет

  • Создаются таблицы вида CREATE TABLE имя (id int(10), поле тип, ...). Первичный ключ, AUTO_INCREMENT, NOT NULL, индексы и внешние ключи не создаются.
  • Добавляются отсутствующие колонки (ALTER TABLE ... ADD COLUMN) и изменяются типы существующих (ALTER TABLE ... MODIFY) — только в режиме optFullUpdate.
  • Удаление и переименование колонок, миграция данных и версионирование схемы не поддерживаются. Порядок колонок при создании таблицы зависит от обхода HashMap и не гарантирован.
  • DDL-операции не объединяются в транзакцию; сбой посередине оставляет схему в промежуточном состоянии.
  • Для работы режима у пользователя MySQL должны быть права на CREATE и ALTER.
  • Функция checkBMSStruct в текущей версии — каркас: она подключается к базе meldadef и читает системные экраны, но цикл сверки пуст. Реальной миграции системных метаданных нет.

Перед запуском с optFullUpdate обязательно сделайте резервную копию базы данных. Изменение типа колонки может привести к потере данных, а отката и истории версий схема не хранит. Для прототипа и быстро меняющейся предметной области режим удобен; для промышленной эксплуатации он не заменяет систему миграций.

Рекомендуемый порядок: сделать резервную копию → убедиться в правах MySQL → включить setOptDBDebugMode(true) и при необходимости setOptMode(OptDB.optFullUpdate) → запустить и прочитать отчёт в консоли → убрать оба вызова и запустить приложение обычным образом.

10. Сборка и запуск приложения

Приложение Melda — обычный Java-проект. Особенность только одна: каркас находит прикладные классы по аннотациям, перечисляя каталоги пакетов, поэтому прикладные классы должны быть доступны на classpath именно как каталоги, а не внутри JAR.

Classpath и рефлексия

Таблица 19. Что должно быть в classpath
КомпонентЗачем
melda2vxlib.jarклассы каркаса; сам JAR может оставаться JAR-файлом
JavaFX: javafx.controls, javafx.media, javafx.webинтерфейс, проигрыватель видео, встроенный браузер
RichTextFXкомпонент CodeEditor
MySQL Connector/JJDBC-драйвер MySQL
каталоги классов приложения (app.*)рефлексия каркаса перечисляет файлы каталогов пакетов

accessReflect получает поток каталога пакета через загрузчик классов, читает строки, оканчивающиеся на .class, и загружает классы. Для каталога на файловой системе это работает, для содержимого JAR — нет: каталог внутри архива не перечисляется, каркас молча не находит ни одного аннотированного класса. Последствия: не строится пользовательское меню, не загружаются инъекции, не регистрируются пользовательские компоненты — сообщений об ошибке при этом нет. Запускайте приложение с каталогом classes (или out/production/...) в classpath; в JAR можно упаковывать саму библиотеку каркаса.

Пример запуска (JavaFX подключён через module-path, версии и пути подставьте свои):

java --module-path "%JAVAFX_LIB%" ^
     --add-modules javafx.controls,javafx.media,javafx.web ^
     -cp "melda2vxlib.jar;mysql-connector-j.jar;out\production\app" ^
     app.FakeMain

Порядок запуска, который обеспечивает каркас:

  1. Авторизация по логину и паролю из bms_users; при неудаче показывается экран авторизации.
  2. Регистрация системных моделей bms_*, затем моделей из USRDataModelsInit, затем заполнение справочников выбора.
  3. Регистрация пользовательских строителей компонентов — до загрузки данных, иначе строки bms_scr_components не отобразятся на классы.
  4. Отладочный режим: миграция схемы и завершение запуска без интерфейса.
  5. Загрузка данных по всем источникам.
  6. Загрузка пользователей, групп и правил.
  7. Обнаружение инъекций.
  8. Построение меню, панели вкладок и окон.

Ровно один класс должен быть помечен @MeldaUserDMInit и ровно один — @MeldaMenuBuilder: каркас использует первый найденный, а порядок обхода каталога не гарантирован. Инъекций и пользовательских строителей может быть сколько угодно — они все попадают в реестры. Аннотация должна быть первой аннотацией класса: каркас сравнивает только первую.

Типовые ошибки

Таблица 20. Типовые ошибки запуска и их причины
СимптомПричинаЧто делать
NullPointerException при построении экранатип компонента не найден: Calendar, ReviewView, устаревший или вручную вписанный код без строителявыбрать тип из списка BMS Setup; для пользовательского типа проверить регистрацию строителя
NullPointerException при построении или открытии экранаимя экрана в меню не совпадает с bms_screens.name; строка экрана отсутствуетсверить имена; пересоздать экран
Экран не открывается, в консоли «Ошибка: не найдено меню …»родительское меню не разрешено правилом или добавлено позже пунктавыдать правило allowvmenu, добавить родителя раньше
Пункт меню есть, клик ничего не делаетпункт добавлен через addMenuInjectEventиспользовать ScreenButton с инъекцией onClick
Нет меню, инъекций и пользовательских компонентов, ошибок нетклассы собраны в JAR; каталоги пакетов не перечисляютсязапускать с каталогами классов в classpath
NullPointerException в MUserGroup или MARuleCheckerу пользователя не заполнено поле ugroup или группа не загруженазаполнить группу и правила; перезапустить
«MELDA ERROR: Username or pass is wrong…»нет строки в bms_users или пароль не совпадает с учётной записью MySQLсверить логин и пароль в bms_users и в MySQL
NullPointerException в строителе навигатораlinkedlist указывает на незарегистрированный списокпроверить имя списка и порядок listInit
Форма не открываетсяlinkedform указывает на несуществующую формусверить bms_forms.name и ссылку
NullPointerException при выборе MultiDateCheckerмультиформа не реализованаиспользовать DateChecker
NoClassDefFoundError: javafx/…JavaFX не подключёндобавить модули JavaFX
NoClassDefFoundError: org/fxmisc/richtext/…RichTextFX не подключёндобавить зависимость или не использовать CodeEditor
«DB SYNC ERROR: CAN’T CONNECT TO DB»MySQL недоступен, неверны хост, база или учётные данныепроверить подключение и права пользователя

11. Ограничения текущей версии

Перечисленные ограничения носят инженерный характер: они не меняют архитектурную идею «модель данных в коде — представление в данных — схема БД из модели», но определяют границы применимости текущей версии — однопользовательская настольная система, умеренные объёмы данных, доверенный контур.

Инженерные ограничения

Таблица 21. Основные ограничения
ПодсистемаОграничениеСледствие
Персистентностьнет транзакцийчастичный сбой оставляет БД и память рассогласованными
БезопасностьSQL собирается конкатенацией, PreparedStatement не используетсязначения, включая логин и пароль, подставляются в текст запроса; возможны SQL-инъекции
Аутентификацияпароль хранится и сравнивается в открытом виде и одновременно служит паролем MySQLкомпрометация базы раскрывает учётные записи; нельзя использовать разные пароли
Производительностьполная загрузка SELECT *, слияние строк и записей двойным циклом (O(n²)), линейный поиск по id, нет индексов и пула соединенийвремя запуска и обновления растёт квадратично; на больших списках приложение замедляется
Идентификацияидентификаторы генерирует приложение; в DDL нет PRIMARY KEY и AUTO_INCREMENTвозможны конфликты при внешних вставках; целостность не гарантируется СУБД
Миграция схемыаддитивная: создание таблиц и колонок, изменение типов; удаление, переименование, ключи, индексы и версионирование отсутствуютсхема не приводится к модели при удалении полей; отката нет
Модель правтолько меню и экраны; прав на списки, записи, поля и операции нетролевая модель на уровне данных реализуется прикладным кодом
СУБДреально поддерживается только MySQLветки typeMeldaQueries и typePostgreSQL объявлены, но не реализованы
Режим работыоднопользовательское настольное приложение; многооконность — вкладки в одном окненет серверного режима и одновременной работы пользователей с общей базой
Потокобезопасностьсинглтоны без синхронизации, общее соединение, запросы в потоке JavaFXдлительные операции блокируют интерфейс
Локализация и диагностикавсе тексты зашиты в код; сообщения выводятся в стандартный поток выводанет механизма переводов, уровней журналирования и файлового журнала
Валидация данныхцентрализованной проверки нет, проверки точечные в элементах формошибки ввода обрабатываются непоследовательно

Заготовки

Ряд подсистем объявлен, но не доведён до рабочего состояния. Их не следует использовать в прикладном коде:

  • DFMultidata — множественная ссылка: собственный тип не задан (наследуется varchar(1)), разбор значения ненадёжен.
  • DFPoint — точка: нет фабрики в DFB, типа, значения и клонирования.
  • mqueries — альтернативный бэкенд: соединение не переопределено, результат пуст.
  • Crypto и шифрование полей: алгоритм реализован, но по умолчанию ни одно поле не шифруется; ключ и вектор заданы в коде статически.
  • MultiForm, MultiDateChecker, PathChecker, MultiDataChecker — мультиформы и дополнительные элементы форм не реализованы.
  • Calendar и ReviewView — типы компонентов объявлены в справочнике, но строителей нет: при выборе возникает NullPointerException.
  • checkBMSStruct — сверка системных метаданных с базой meldadef осталась каркасом.
  • bms_access_list_rules и bms_user_subordinates — таблицы объявлены, но не используются проверками.

Отдельные дефекты реализации, которые следует учитывать при проектировании: денежное поле хранится как float, но в БД пишется в int (дробная часть теряется); для списков listInitUsered автоматическое создание таблицы не добавляет колонку meldauser; проверка протокола DFURL ослаблена и не является валидацией; выравнивания 4, 5 и 6 объявлены, но BorderScreenComponent их не размещает; VideoViewer ожидает в списке жёстко заданные поля path и file1080p и локальный каталог видео.

Приложение. Ключевой API

Сводка основных вызовов каркаса. Полные сигнатуры и внутреннее устройство классов приведены в техническом описании.

Таблица 22. Фасад Melda
МетодНазначение
Melda.i()единственный экземпляр фасада
setAppName(String)имя приложения в заголовке окна и сообщениях
setAppPackage(String)базовый пакет расширений, например app
createDBSyncDefault(host, port, dbName, type)основной источник данных; type — DBSync.typeMySQL
createDBSync(name, host, port, dbName, type)дополнительный именованный источник данных
setUserAndPass(login, pass)авторизация и учётные данные JDBC
init(Stage)запуск каркаса
setOptDBDebugMode(boolean)отладочный режим миграции схемы
setOptMode(int)режим OptDB: optOnlyCheck, optCreateTables, optFullUpdate, optShowDataLists
getMeldaUI()доступ к интерфейсу: getCollector(), getMenuBuilder()
Таблица 23. Строитель полей DFB
МетодНазначение
dfString(name, title, maxChars)строка; maxChars — число или константа DFString.charsCount*
dfBoolean(name, title), dfInteger(name, title)логическое и целое поля
dfMoney(name, title, valType)денежная сумма; DFMoney.mRUB, mUSD, mEURO
dfDate(name, title), dfTime(name, title)дата и время
dfChoice(name, title, maxChars)выбор из справочника; значения добавляются addChoiceValues(ключ, значение)
dfData(name, title, listName)ссылка на запись; отображаемые поля — addShowedFields(name)
dfMultiData(name, title, listName)множественная ссылка (заготовка)
dfFile(name, title, hostName)файл; настройки — setFilePath, setFileValueWithPath, addFileExt
dfURL(name, title, linkType), dfTel(name, title)ссылка и телефон
dfHashTegs(name, title, DataList, fieldName)набор меток
Таблица 24. Регистрация и расширения
ВызовНазначение
listInit(dm, name, dbSyncName) и варианты listInitUsered, listInitCrypto, listInitUseredCryptoрегистрация списка в USRDataModelsInit
MenuBuilder.addMenu / addMenuScreen / addMenuInjectEventпостроение меню; пункт-инъекция не исполняется
InjectMethod.setWindowName / setComponentName / setEventNameпривязка инъекции к тройке «окно — компонент — событие»
ComponentBuilder.buildComponent(dc, window, source)создание пользовательского компонента по строке метаданных
accessDataRegistry.i().getDataList(name)доступ к списку по имени (источник default)
accessDataRegistry.i().getDataList(name, dbSyncName)доступ к списку в именованном источнике
accessDataRegistry.i().updateData()синхронизация всех списков с БД
accessUsers.i().getCurrentUser()текущий пользователь, его группа и правила
accessVars.i().createNewVar(context, name, value)создание переменной окна или коллектора

Дополнительные материалы — примеры приложений на Melda, техническое описание подсистем и обсуждение на форуме. Материалы для загрузки — на странице «Загрузки».