Руководство по разработке
Практическое руководство по разработке приложений на фреймворке Melda: установка окружения и первый запуск, модель данных и её отображение на схему MySQL, меню, пользовательские компоненты, инъекции, формы и метаданные интерфейса, права доступа, фильтры, отладка и миграция схемы БД, сборка приложения. Примеры сверены с исходным кодом каркаса; места, где прежняя документация расходилась с реализацией, отмечены отдельно.
Быстрый старт
Приложение на Melda — это обычный Java-проект, который подключает библиотеку каркаса, описывает модель данных классами DataModel и передаёт управление фасаду Melda. Каркас создаёт схему базы данных, загружает метаданные интерфейса, строит окна и меню, проверяет права пользователя.
Требования к окружению
| Компонент | Назначение | Примечание |
|---|---|---|
| JDK (Java SE) | компиляция и запуск приложения | минимальная версия в исходниках не зафиксирована; код написан без модульной системы |
| JavaFX | пользовательский интерфейс | начиная с JDK 11 поставляется отдельно — SDK или зависимости проекта |
| RichTextFX | редактор кода с подсветкой | нужен только для компонента CodeEditor (тип code) |
| MySQL | хранение данных и метаданных интерфейса | единственная поддерживаемая СУБД |
| MySQL Connector/J | JDBC-драйвер | должен быть в classpath приложения |
melda2vxlib.jar | библиотека каркаса | подключается к проекту как обычная библиотека |
meldadb.sql | прототип базы данных | содержит системные таблицы bms_* и стартовое наполнение |
Порядок подготовки проекта:
- Подключить к проекту библиотеку
melda2vxlib.jar, JavaFX (модулиjavafx.controls,javafx.media,javafx.web) и RichTextFX. - Развернуть прототип базы данных
meldadb.sqlв MySQL. - Создать пользователя СУБД
meldarootи предоставить ему полные права на базу данных, включаяCREATEиALTER: каркас изменяет схему при миграции. - Внести учётную запись
meldarootв таблицуbms_users. - Создать структуру пакетов приложения и обязательные классы (см. ниже).
- Собрать проект и запустить стартовый класс.
Логин и пароль в 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);
}
}
Первый запуск
- Собрать проект: библиотека каркаса, JavaFX, RichTextFX и драйвер MySQL должны попасть в classpath.
- Запустить
app.FakeMain. При запуске приложение авторизуется по учётной записи, переданной вsetUserAndPass. - Убедиться, что в базе существуют системные таблицы
bms_*и строка пользователя вbms_users. Если таблиц нет, включите отладочный режим с миграцией схемы (раздел 9). - Открыть системное меню 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 — одновременное существование трёх моделей, описанных разными средствами и играющих разные роли.
| Модель | Где описана | Что определяет |
|---|---|---|
| Модель данных | типизированный 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.
| Тип | Добавление | SQL-тип | Особенности |
|---|---|---|---|
DFString | DFB.dfString(имя, надпись, максСимволов) | varchar(n) или tinytext/text/mediumtext/longtext | положительное число символов → varchar(n); спецконстанты — текстовые типы; длина проверяется в setValue |
DFBoolean | DFB.dfBoolean(имя, надпись) | varchar(1) | в БД '0'/'1'; в записях — «да»/«нет» (см. примечание ниже) |
DFInteger | DFB.dfInteger(имя, надпись) | int | getIntValue/setIntValue, проверка числа при разборе |
DFMoney | DFB.dfMoney(имя, надпись, валюта) | int | валюта DFMoney.mRUB, mUSD, mEURO; значение хранится как float, но SQL-тип — int |
DFDate | DFB.dfDate(имя, надпись) | date | значение через TimeMoment; в интерфейсе дд.мм.гггг, в БД — гггг-м-д без ведущих нулей (MySQL нормализует дату при хранении) |
DFTime | DFB.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:
| Метод | Назначение |
|---|---|
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)
| Параметр | Назначение |
|---|---|
name | имя компонента из BMS Setup; по нему компонент находится в дереве и к нему привязываются инъекции |
sourceComponent | родительский компонент, обычно корневой компонент экрана; передаётся каркасом |
dataSource | Melda-список, данные которого отображает компонент; берётся из поля linkedlist |
selectedFields | выбранные поля источника данных; в BMS Setup задаются шаблоном в поле options |
title | надпись компонента из поля title |
align | код расположения на экране; полностью управляется Melda |
Жизненный цикл компонента
buildPane()— создаёт визуальное представление компонента и обязана заполнить защищённое полеpane(JavaFXPane). Вызывается из конструктора компонента; без неё каркас не сможет разместить компонент на экране.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.
| Место | Значение |
|---|---|
| комбобокс в 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сравнивает только окно, компонент и событие. Имя сохранено для совместимости и будущего механизма меню-инъекций.
Список инъекций строится один раз при запуске, после загрузки данных. Добавленные или изменённые классы инъекций начинают работать после перезапуска приложения. У класса должен быть публичный конструктор без параметров: каркас создаёт его рефлексией.
События и параметры
| Событие | Компоненты | Параметры pars | Когда вызывается |
|---|---|---|---|
onUpdate | компоненты на базе Component (в том числе ScreenButton), ScreenLabel, TableNavigator, контейнер экрана | null | при каскадном обновлении окна |
onClick | ScreenButton, ScreenLabel | null | по клику мышью |
onSelectRow | TableNavigator, ListNavigator, ComboNavigator | pars.get(0) — NavigatorRow | при выборе строки или элемента |
colorRow | TableNavigator | pars.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_*; изменения вступают в силу после перезапуска приложения.
bms_forms, bms_form_groups и bms_form_elements.Таблицы форм
| Таблица | Поля | Назначение |
|---|---|---|
bms_forms | name (100), title (200), type (1), linkedlist (50) | форма: имя, заголовок, тип и список-источник |
bms_form_groups | form (ссылка на форму), title (100), align (1) | группа полей формы |
bms_form_elements | formg (ссылка на группу), 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.
Элементы форм
| Тип | Код | Реализация |
|---|---|---|
BooleanChecker | 1 | выпадающий список «Да/Нет» для поля DFBoolean |
ChoiceChecker | 2 | выпадающий список значений поля DFChoice |
DataChecker | 3 | выбор связанной записи через диалог; поддерживается viewtype = 1 |
DateChecker | 4 | день, месяц, год и кнопка календаря (класс DateCheker) |
MultiDateChecker | 5 | не реализован: обращение к несозданной мультиформе приводит к NullPointerException |
TextInput | 6 | однострочное поле ввода с проверкой длины поля |
TimeInput | 7 | ввод часов, минут и секунд |
BigTextInput | 8 | многострочное поле ввода |
PathChecker | 9 | объявлен в справочнике, но не реализован: элемент молча пропускается |
MultiDataChecker | 10 | объявлен в справочнике, но не реализован: элемент молча пропускается |
| Значение | Код | Применение |
|---|---|---|
Standard | 1 | единственный реализованный вариант для DataChecker |
Minimal | 2 | объявлен, для DataChecker не реализован |
Middle | 3 | объявлен, для DataChecker не реализован |
Extended | 4 | объявлен, для DataChecker не реализован |
Централизованной валидации у элементов формы нет: проверки выполняются точечно внутри элементов, сообщения об ошибках не предусмотрены. Отмена редактирования не требует отката: форма работает с копией полей, а запись изменяется только по нажатию «Добавить» или «Изменить».
Экраны и компоненты
| Таблица | Поля | Назначение |
|---|---|---|
bms_screens | name (50), title (200) | экран: идентификатор и заголовок вкладки |
bms_scr_components | name (50), screen, type (10), title (200), linkedlist (50), align (2), options (200), linkedform | компонент экрана: тип, источник данных, выравнивание, шаблон и связанная форма |
Поле type — это выбор из справочника. В комбобоксе отображается полное имя, в БД хранится короткий код. Встроенные значения:
| Тип | Код в БД | Визуализация |
|---|---|---|
ScreenLabel | scrlbl | надпись; клик вызывает onClick |
ScreenButton | scrbtn | кнопка; клик вызывает onClick |
ListNavigator | lstnav | список ListView; шаблон строки в options |
TableNavigator | tabnav | таблица TableView; колонки по выбранным полям |
HListNavigator | hlnav | дерево TreeView; иерархия по полю-родителю |
ComboNavigator | cmbnav | выпадающий список ComboBox |
CodeEditor | code | редактор кода RichTextFX; в options — два поля: заголовок и содержимое |
VideoViewer | vidvw | проигрыватель JavaFX Media; в options нужны два поля (иначе ошибка), но сам компонент ожидает в списке поля path и file1080p |
Calendar | cal | объявлен в справочнике, но строителя нет — при выборе будет NullPointerException |
ReviewView | revvw | объявлен в справочнике, но строителя нет — при выборе будет NullPointerException |
Шаблон options задаёт выбранные поля в квадратных скобках: для таблицы — [coursename] [title], для списка — [coursename]; для иерархического навигатора шаблон имеет вид <coursecats>{path}[title], где <coursecats> — необязательное имя списка, {path} — поле пути, далее шаблон строки.
| Код | Значение справочника | Фактическое размещение |
|---|---|---|
| 1 | FullCenter | центр экрана; несколько компонентов с кодом 1 перекрывают друг друга |
| 2 | VBoxLeft | левая колонка |
| 3 | VBoxRight | правая колонка |
| 4 | VBoxFull | объявлен, но при размещении не используется |
| 5 | HBoxTop | объявлен, но при размещении не используется |
| 6 | HBoxBottom | объявлен, но при размещении не используется |
| 7 | VBoxCenter | центральная колонка |
Связанная форма (linkedform) используется навигаторами: по ней строятся окна создания и изменения записи. Если форма не указана, навигатор работает только на просмотр. Источник данных (linkedlist) — имя зарегистрированного Melda-списка.
Пошаговый рецепт
Типовой порядок добавления новой сущности в приложение:
- Модель и список. Создать класс-наследник
DataModelвapp.models, описать поля черезDFBи зарегистрировать список вUSRDataModelsInitметодомlistInit(...). При необходимости создать таблицу в БД через отладочный режимOptDB(раздел 9). - Форма. В BMS Setup → Forms создать форму:
name,title. Полеlinkedlistу формы в текущей версии не читается — список форма получает от навигатора, поэтому связанная форма должна открываться из навигатора с правильнымlinkedlist. Добавить группы (заголовок и выравнивание) и элементы: тип, надпись,fieldnameиз модели. Для ссылочного поля —DataCheckerсоviewtype= 1. - Экран. В BMS Setup → Screens создать экран (
name,title), затем компоненты: навигатор сlinkedlist, шаблономoptions, связанной формойlinkedform; при необходимости — надписи и кнопки. - Меню. В
USRMenuBuilderдобавить пункт:addMenuScreen("Родитель", "Пункт", "имяЭкрана"). Родительское меню должно быть добавлено раньше пункта. - Права. В BMS Setup → Users and rules выдать текущей группе или пользователю правило с
allowvmenuдля родительского меню и пункта, а также правило сallowvscreenдля экрана. Без правил пункт не отображается. - Перезапуск. Метаданные и меню читаются при запуске; после изменений перезапустить приложение и проверить экран, форму и права.
Если после создания экрана при открытии возникает NullPointerException без сообщения, проверьте три вещи: имя экрана в addMenuScreen совпадает с bms_screens.name; у каждого компонента тип имеет строителя; linkedlist указывает на зарегистрированный список.
7. Пользователи, группы и права доступа
Авторизация выполняется по таблице bms_users: при запуске каркас запрашивает строку с логином и паролем и тем же логином и паролем открывает соединение с MySQL. После загрузки данных пользователи, группы и правила читаются в память; проверка прав выполняется при построении меню и при открытии экрана.
Пользователи и группы
| Таблица | Поля | Назначение |
|---|---|---|
bms_users | ulogin (50), upass (50), uname (100), usecname (100), usurname (100), position (100), ugroup (ссылка на группу) | учётные записи; логин и пароль одновременно служат учётными данными MySQL |
bms_user_groups | gname (200) | группы пользователей |
bms_access_rules | mgroup (ссылка на группу), muser (ссылка на пользователя), allowvmenu (100), allowvscreen (ссылка на экран) | белые списки: разрешение меню и экрана для группы или пользователя |
bms_access_list_rules | mgroup, muser, dlistname, allowview, allowadd, allowchange | объявлена, но не используется ни одной проверкой |
bms_user_subordinates | muser (руководитель), msubuser (подчинённый) | объявлена, в текущей версии не используется |
Учётная запись meldaroot должна быть внесена в bms_users и привязана к группе. Ей, как правило, выдан доступ к системному меню BMS Setup. Если поле ugroup пусто, при загрузке пользователей возникает NullPointerException: класс MUserGroup строится из ссылки на группу без проверки на null. Та же ошибка возникнет при проверке прав, если группа не загружена.
Правила доступа
Правило MAccessRule содержит ровно два атрибута: allowViewMenu (строка — заголовок меню или пункта) и allowViewScreen (ссылка на запись экрана). Проверка устроена как белый список с приоритетом групповых правил:
- Если разрешение найдено в правилах группы текущего пользователя, доступ разрешается.
- Иначе проверяются личные правила пользователя.
- Если разрешения нет ни там, ни там, доступ запрещён.
Меню и экран проверяются отдельно: для отображения пункта нужно правило allowvmenu с точным заголовком пункта, а для открытия экрана — правило allowvscreen с нужным экраном. Родительское меню также требует собственного правила; без него дочерние пункты не строятся.
Прав на данные нет. Механизм разграничивает только меню и экраны; прав на списки, записи, поля и операции (чтение, добавление, изменение, удаление) в текущей версии не существует. Таблица bms_access_list_rules объявлена, но не участвует в проверках. Для ролевой модели, различающей, например, администратора, преподавателя и обучающегося по данным, механизма недостаточно — такие ограничения реализуются прикладным кодом.
Правила и группы читаются при запуске; после изменения таблиц в BMS Setup → Users and rules приложение нужно перезапустить. Пароль хранится в открытом виде и совпадает с паролем MySQL — это ограничение текущей реализации (раздел 11).
8. Фильтры и переменные
Фильтры ограничивают набор записей, отображаемых навигатором или полем выбора формы. Они хранятся в таблице bms_filters и читаются при построении экрана или открытии формы; изменение фильтров требует перезапуска приложения.
Таблица bms_filters
| Поле | Тип | Назначение |
|---|---|---|
scrnav | ссылка на bms_scr_components | компонент экрана, к которому применяется фильтр |
formcomp | ссылка на bms_form_elements | элемент формы, к которому применяется фильтр (для поля выбора) |
field | varchar(20) | имя поля источника данных |
relation | выбор: ==, !=, cn | отношение: равно, не равно, содержит |
expression | varchar(100) | выражение: литерал, переменная или data-команда |
def | boolean | объявлено как «По умолчанию», но в коде не читается |
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, а фильтр второго навигатора подставляет эту переменную.
| Поле | Значение |
|---|---|
scrnav | компонент coursesnav |
field | coursecat |
relation | == |
expression | $catnav |
logictype | AND |
Пока категория не выбрана, переменная равна -1, и второй навигатор не показывает записей. После выбора строки каркас обновляет окно, и детали перестраиваются. Фильтры можно комбинировать: несколько строк с logictype = AND/OR объединяются последовательно, первый фильтр применяется к полному набору записей.
9. Отладка и миграция схемы БД
Melda умеет приводить схему базы данных к модели: создавать отсутствующие таблицы и колонки, изменять типы колонок. Эта операция выполняется только в отладочном режиме optDBDebugMode — в обычном запуске каркас схему не меняет.
Режимы OptDB
| Константа | Значение | Поведение |
|---|---|---|
OptDB.optOnlyCheck | 1 | только диагностика: схема не изменяется; режим по умолчанию |
OptDB.optCreateTables | 2 | создание отсутствующих таблиц; колонки не добавляются и не изменяются |
OptDB.optFullUpdate | 3 | создание таблиц и колонок, изменение типов существующих колонок |
OptDB.optShowDataLists | 4 | диагностическая печать содержимого списков; схема не изменяется |
Включение режима
Режим включается в методе 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 и рефлексия
| Компонент | Зачем |
|---|---|
melda2vxlib.jar | классы каркаса; сам JAR может оставаться JAR-файлом |
JavaFX: javafx.controls, javafx.media, javafx.web | интерфейс, проигрыватель видео, встроенный браузер |
| RichTextFX | компонент CodeEditor |
| MySQL Connector/J | JDBC-драйвер 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
Порядок запуска, который обеспечивает каркас:
- Авторизация по логину и паролю из
bms_users; при неудаче показывается экран авторизации. - Регистрация системных моделей
bms_*, затем моделей изUSRDataModelsInit, затем заполнение справочников выбора. - Регистрация пользовательских строителей компонентов — до загрузки данных, иначе строки
bms_scr_componentsне отобразятся на классы. - Отладочный режим: миграция схемы и завершение запуска без интерфейса.
- Загрузка данных по всем источникам.
- Загрузка пользователей, групп и правил.
- Обнаружение инъекций.
- Построение меню, панели вкладок и окон.
Ровно один класс должен быть помечен @MeldaUserDMInit и ровно один — @MeldaMenuBuilder: каркас использует первый найденный, а порядок обхода каталога не гарантирован. Инъекций и пользовательских строителей может быть сколько угодно — они все попадают в реестры. Аннотация должна быть первой аннотацией класса: каркас сравнивает только первую.
Типовые ошибки
| Симптом | Причина | Что делать |
|---|---|---|
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. Ограничения текущей версии
Перечисленные ограничения носят инженерный характер: они не меняют архитектурную идею «модель данных в коде — представление в данных — схема БД из модели», но определяют границы применимости текущей версии — однопользовательская настольная система, умеренные объёмы данных, доверенный контур.
Инженерные ограничения
| Подсистема | Ограничение | Следствие |
|---|---|---|
| Персистентность | нет транзакций | частичный сбой оставляет БД и память рассогласованными |
| Безопасность | 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
Сводка основных вызовов каркаса. Полные сигнатуры и внутреннее устройство классов приведены в техническом описании.
| Метод | Назначение |
|---|---|
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() |
| Метод | Назначение |
|---|---|
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) | набор меток |
| Вызов | Назначение |
|---|---|
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, техническое описание подсистем и обсуждение на форуме. Материалы для загрузки — на странице «Загрузки».