Техническое описание фреймворка Melda
Настоящий документ — справочное описание внутреннего устройства каркаса Melda, подготовленное по результатам статического анализа исходного кода пакета MELDAVX (Java и JavaFX). Версия документа 1.0. Назначение — служить справочником по архитектуре, подсистемам и текущей реализации каркаса; приёмы прикладной разработки вынесены в отдельное руководство. Смежные страницы раздела: руководство по разработке, загрузки и обзор проекта MeldaVX.
1. Общие сведения о каркасе
1.1. Назначение
Melda — встраиваемый каркас (библиотека) для быстрой разработки информационных систем, управляемых данными. Каркас не является готовым приложением: он подключается к прикладному проекту и берёт на себя четыре задачи:
- описание модели данных и её отображение на схему реляционной базы;
- загрузку и сохранение данных без написания SQL прикладным разработчиком;
- построение пользовательского интерфейса по метаданным, хранящимся в базе;
- разграничение доступа на уровне меню и экранов.
Прикладной разработчик описывает предметную область классами-наследниками DataModel (набор типизированных полей) и подключает их к источнику данных; дальнейшее поведение системы — создание таблиц, экранов, навигаторов, форм — определяется метаданными, которые можно изменять без пересборки приложения.
1.2. Технологический стек и зависимости
Каркас реализован на Java и JavaFX. Внешние зависимости сведены к минимуму: стандартная библиотека JDK (java.util, java.io, java.sql, javax.crypto), JavaFX (графический интерфейс) и библиотека RichTextFX (org.fxmisc.richtext), используемая только компонентом CodeEditor. Фреймворков внедрения зависимостей, ORM, контейнеров сервлетов и систем логирования в составе каркаса нет.
| Зависимость | Назначение в каркасе | Масштаб использования |
|---|---|---|
| Java SE (JDK) | язык и стандартная библиотека | все пакеты |
| JavaFX | построение интерфейса (Pane, Scene, Stage, контролы) | пакет windowmodel, класс Melda |
| java.sql (JDBC) | доступ к СУБД | dbsyncs.mysql |
| javax.crypto | симметричное шифрование строк | datamodel.Crypto |
| RichTextFX | редактор кода с подсветкой | windowmodel.components.CodeEditor |
1.3. Метрики кодовой базы
Измерения выполнены по исходному дереву src: 163 файла основного кода и 6 файлов тестового приложения (демонстрация прикладного API).
| Показатель | Значение |
|---|---|
| Файлов Java (main / test) | 163 / 6 |
| Строк кода (main / test) | 11 153 / 156 |
| Непустых строк (main) | 9 035 |
| Пакетов верхнего уровня | 13: корневой MELDAVX и 12 подпакетов первого уровня |
| Крупнейший пакет | windowmodel — 76 файлов, 5 441 строка (≈ 49 % кода) |
| Крупнейшие классы | TableNavigator (386), HListNavigator (382), DBSync (313), FormWindowBuilder (255), Melda (254) |
| Встроенных типов компонентов экрана | 8 |
| Типов элементов формы | 8 |
| Таблиц метаданных интерфейса | 6 |
| Системных моделей данных (bms_*) | 13 |
Крупнейший пакет — windowmodel: 76 файлов и 5 441 строка, около 49 % всего кода. Самыми объёмными классами остаются TableNavigator (386 строк), HListNavigator (382), DBSync (313), FormWindowBuilder (255) и Melda (254).
1.4. Структура пакетов
Пакеты верхнего уровня перечислены в таблице 3. С учётом вложенных подпакетов в кодовой базе 29 пакетов; ниже пакеты верхнего уровня показаны вместе с вложенными там, где это важно для понимания структуры.
| Пакет | Файлов | Строк | Назначение |
|---|---|---|---|
| MELDAVX (корень) | 3 | 388 | фасад Melda, сборка интерфейса MeldaUI, служебный Controller |
| annotations | 4 | 33 | маркеры точек расширения |
| calendar | 3 | 303 | даты, время, календарная сетка |
| datacmds | 4 | 181 | подстановки getDC и getDF в выражениях фильтров |
| datamodel | 6 | 576 | DataModel, DataClass, DataList, реестр, счётчик идентификаторов, Crypto |
| datamodel.datafields | 16 | 1 589 | DataField, 14 наследников и строитель DFB |
| datamodelinit (+ defmodels) | 16 (3 + 13) | 479 (103 + 376) | инициализация моделей и системные модели bms_* |
| dbsyncs (+ mqueries, mysql, mysql.queries) | 24 (7 + 3 + 3 + 11) | 1 451 | синхронизация с БД, генерация SQL, миграция схемы |
| injects | 1 | 49 | реестр инъекций и вызов событий |
| reflect | 1 | 138 | обнаружение аннотированных классов |
| users | 5 | 315 | пользователи, группы, правила доступа |
| usrcomponents | 1 | 97 | пользовательские строители компонентов |
| vars | 3 | 113 | переменные и контексты переменных |
| windowmodel (+ подпакеты) | 76 | 5 441 | компоненты, окна, навигаторы, формы, меню |
| Итого | 163 | 11 153 | — |
2. Архитектура каркаса
2.1. Концепция: три модели вместо одной
Архитектурная особенность Melda состоит в том, что в системе одновременно существуют три модели, описанные разными средствами и играющие разные роли.
- Модель данных (в коде). Класс-наследник DataModel содержит список прототипов полей DataField, созданных строителем DFB. Модель типизирована средствами языка, проверяется компилятором и участвует в рефакторинге.
- Модель представления (в базе данных). Экраны, компоненты экранов, формы, группы полей, элементы форм и фильтры хранятся строками в шести таблицах: bms_screens, bms_scr_components, bms_forms, bms_form_groups, bms_form_elements, bms_filters. Изменение этих строк меняет интерфейс без пересборки приложения.
- Системная модель (самоописание). Пользователи, группы, правила доступа и сами метаданные интерфейса описаны теми же средствами — классами DataModel в пакете datamodelinit.defmodels. Каркас применяет свой механизм метаданных к собственным метаданным, то есть модель рефлексивна.
Такое разделение — ключевое архитектурное решение: типизированная часть (структура данных) остаётся в языке программирования, а изменяемая часть (состав и параметры экранов) выносится в данные.
2.2. Слои
| Слой | Ключевые классы | Ответственность |
|---|---|---|
| Прикладной | наследники DataModel, MenuBuilder, InjectMethod, ComponentBuilder | описание предметной области и расширений |
| Фасад и жизненный цикл | Melda, MeldaUI | конфигурация, авторизация, порядок запуска |
| Модель данных | DataField, DF*, DFB, DataModel, DataClass, DataList, accessDataRegistry | хранение значений в памяти, типизация, идентификация записей |
| Персистентность | DBSync, DBSMySQL, DBSConnection, DBSResult, DBSQuery | загрузка и сохранение, генерация SQL, маппинг типов |
| Миграция схемы | OptDB | сверка модели с БД, аддитивное изменение схемы |
| Интерфейс | Component, Window, WindowCollector, Navigator*, BaseForm, FormWindowBuilder, ScreenWindowBuilder, MeldaMenu | построение и обновление UI по метаданным |
| Доступ | MUser, MUserGroup, accessUsers, MAccessRule, MARuleChecker | аутентификация, правила отображения |
| Расширения | accessReflect, accessInjects, InjectMethod, аннотации | обнаружение и подключение прикладного кода |
2.3. Направления зависимостей
Зависимости однонаправлены: интерфейс зависит от модели данных и через accessInjects — от расширений; модель данных не зависит от интерфейса; персистентность зависит от модели данных, но не от интерфейса. Единственная точка, где слои сходятся, — фасад Melda, который в методе init связывает инициализацию моделей, загрузку данных, пользователей и запуск интерфейса.
приложение (app.*)
│ DataModel, MenuBuilder, ComponentBuilder, InjectMethod
▼
MELDAVX.Melda ──► MeldaUI ──► windowmodel (Component, Window, Navigator, Form)
│ ▲
▼ │ accessInjects
datamodel ◄── dbsyncs (DBSync, OptDB) ──► JDBC / MySQL
▲
└── datamodelinit (defmodels: bms_*)
2.4. Минимальный сценарий разработки
Прикладное приложение состоит из точки входа и нескольких классов, помеченных аннотациями. Точка входа конфигурирует каркас и передаёт ему управление:
public class TestMain extends Application {
@Override
public void start(Stage stage) {
Melda.i().setAppName("Melda Test App");
Melda.i().setAppPackage("app");
Melda.i().createDBSyncDefault("host", 3306, "db", DBSync.typeMySQL);
Melda.i().setUserAndPass("user", "pass");
Melda.i().init(stage);
}
}
Модель данных объявляется наследником DataModel и регистрируется в классе, помеченном @MeldaUserDMInit:
public class TestDataModel extends DataModel {
@Override
public void init() {
this.add(DFB.dfString("channelname", "Channel Name", 100));
this.add(DFB.dfString("description", "Channel Description", DFString.charsCountMedium));
this.add(DFB.dfDate("crdate", "Creation Date"));
}
}
@MeldaUserDMInit
public class USRDataModelsInit extends DataModelsInit {
@Override
public void init() {
listInit(new TestDataModel(), "testdata", "default");
}
}
Меню строится программно классом, помеченным @MeldaMenuBuilder:
@MeldaMenuBuilder
public class USRMenuBuilder extends MenuBuilder {
@Override
public void build() {
addMenu("Тестовое меню");
addMenuScreen("Тестовое меню", "Тестовый экран", "testScreen");
}
}
3. Подсистема модели данных
3.1. DataField — базовый тип поля
DataField — прототип поля. Он хранит имя (name), заголовок (title), тип (type), строковое представление значения (value) и флаг updated. Значение любого типа хранится строкой; типоспецифичная логика (разбор, проверка, преобразование в представление БД) вынесена в наследников через методы setValue, getDBStringValue, updateStringValue, setFieldValue, moreThen и clone. Базовый clone возвращает null, поэтому каждый рабочий тип обязан его переопределить — иначе клонирование модели в запись нарушается.
Константы типов заданы целыми числами: typeBool = 0, typeInt = 1, typeString = 2, typeData = 3, typeDate = 6, typeChoice = 7, typeTime = 8, typeHashtegs = 10, typeURL = 11, typeTel = 12, typeMoney = 13, typeFile = 14. Значения 4, 5 и 9 не используются.
3.2. Иерархия типов полей
Наследники DataField образуют набор типов, покрывающий прикладные потребности информационной системы. Таблица показывает назначение типа, фактическое SQL-представление по единственному маппингу DBSMySQL.getTypeOfDataField и особенности реализации.
| Тип | Назначение | SQL-тип | Особенности |
|---|---|---|---|
| DFString | строка | varchar(n) либо tinytext / text / mediumtext / longtext по maxChars | ограничение длины в setValue; флаг encrypted объявлен, но setEncrypted(true) в каркасе не вызывается |
| DFInteger | целое | int | getIntValue и setIntValue; при ошибке разбора setValue возвращает false |
| DFBoolean | логическое | varchar(1) | в памяти «да» / «нет», в MySQL — значения '0' / '1'; setValue нормализует, а конструктор и setBoolValue записывают '1' / '0' напрямую |
| DFChoice | выбор из справочника | varchar(n) | valueMap «ключ → отображаемое значение»; в памяти хранится ключ, в БД — отображаемая строка |
| DFData | ссылка на запись | int | хранит id; при отсутствии ссылки getDBStringValue возвращает -1 |
| DFMultidata | множественная ссылка | varchar(1) — тип не задан | setValue неработоспособен; type остаётся typeBool, поэтому маппинг даёт varchar(1), а не text |
| DFDate | дата | date | значение через TimeMoment; в БД год-месяц-день без ведущих нулей |
| DFTime | время | time | разбор часы / минуты / секунды; значение 00:00:00 отображается как 23:59:59 |
| DFMoney | денежная сумма | int | type = typeInt, поэтому ветка float в DBSMySQL.getTypeOfDataField недостижима |
| DFFile | файл | varchar(500) | локальный путь либо удалённый хост; путь и расширения задаются модификаторами DFB |
| DFURL | ссылка | varchar(300) | разбор на протокол / сайт / документ; типы ссылок HTTP, FTP, mailto, WhatsApp, Telegram |
| DFTel | телефон | varchar(20) | без собственной логики |
| DFHashtegs | набор меток | text | проверка меток по справочнику хештегов |
| DFPoint | точка | varchar(1) — тип не задан | заготовка: нет значения и clone; type остаётся typeBool |
3.3. Строитель DFB
DFB — статический строитель, сокращающий объявление модели до одной строки на поле. Методы dfString, dfInteger, dfBoolean, dfChoice, dfData, dfMultiData, dfDate, dfTime, dfFile, dfURL, dfTel, dfMoney и dfHashTegs возвращают готовый прототип. Для составных типов предусмотрены модификаторы: addShowedFields задаёт поля справочника, отображаемые в навигаторе (DFData, DFMultidata); addChoiceValues пополняет valueMap; setFilePath, setFileValueWithPath и addFileExt настраивают DFFile. Реализация опирается на статическое поле tfield, поэтому вызовы модификаторов должны непосредственно следовать за созданием поля и не являются потокобезопасными.
3.4. DataModel, DataClass, DataList
DataModel наследует ArrayList<DataField> и представляет собой шаблон: метод init наполняет список прототипами, а cloneModelToFields создаёт для новой записи глубокую копию каждого прототипа с обнулённым значением. DataClass — запись: идентификатор id, набор клонированных полей, владелец user (для списков с признаком usered) и три флага состояния added, updated, removed. Именно эти флаги образуют единицу работы, которую впоследствии разбирает подсистема синхронизации.
DataList — именованная коллекция записей, привязанная к источнику данных строкой dbSyncName. Список хранит модель, счётчик идентификаторов DataIdCounter, необязательный ключ шифрования (setCryptoKey) и признак usered. Поиск записи выполняется линейным перебором (getDataById), метод sortByField реализует сортировку в памяти с квадратичной сложностью и без проверки границ, а параметр onServer не используется — серверная сортировка не реализована.
3.5. Реестр accessDataRegistry
Синглтон-реестр хранит три коллекции: списки данных (dataLists), счётчики идентификаторов и источники данных (dbSyncs) с именами по умолчанию. Методы createDBSyncMySQL и createDBSyncMQueries регистрируют источник, getDataList(name[, dbSyncName]) выполняет поиск списка, updateData — загрузку данных по всем источникам, кроме служебного источника с именем meldadef. Реестр также владеет экземпляром OptDB, то есть связывает модель данных с механизмом миграции схемы. Перегрузка getDataList(name) просматривает только списки с именем источника default, что при нескольких источниках даёт скрыто пустой результат.
4. Подсистема персистентности
4.1. Конвейер синхронизации DBSync
DBSync — центральный класс подсистемы (313 строк). Он реализует шаблонный метод updateData, единый для всех списков: сначала выполняются UPDATE для записей с флагом updated, затем INSERT для added, затем DELETE для removed, после чего выполняется SELECT для пополнения памяти. Конкретные действия делегированы наследнику (DBSMySQL), а генерация текста запросов — иерархии DBSQuery.
Авторизация выполняется методом author(). Вызов Melda.setUserAndPass (и экран входа) создаёт MUser с логином и паролем, назначает его текущим пользователем и передаёт источнику данных; DBSConnectionMySQL использует те же логин и пароль как учётные данные JDBC-подключения (DriverManager.getConnection). Затем author() открывает соединение и выполняет запрос SELECT * FROM bms_users WHERE (ulogin='…' AND upass='…'); совпадение подтверждает вход. Таким образом, логин и пароль одновременно являются учётными данными СУБД и прикладной аутентификацией, а пароль хранится в bms_users открытым текстом.
Загрузка (recieveNewData) выполняет SELECT * FROM <таблица> без условий и ограничений: метода установки специализированного запроса у DataList нет, поэтому ветка buildSelectSpecQuery недостижима. Результат сливается с уже загруженными записями двойным циклом «строка × запись» (O(n²)). Отдельного кэша нет: роль кэша выполняет сам DataList в оперативной памяти.
4.2. Генерация SQL
Текст запросов собирается конкатенацией строк. Классы семейства DBSQ*MySQL формируют конкретные операторы: DBSQCreateTableMySQL (CREATE TABLE), DBSQCreateFieldMySQL (ALTER TABLE ... ADD COLUMN), DBSQUpdateFieldTypeMySQL (ALTER TABLE ... MODIFY), DBSQInsertMySQL (INSERT), DBSQUpdateMySQL (UPDATE), DBSQRemoveMySQL (DELETE), DBSQSelectMySQL (SELECT), DBSQSelectTablesMySQL (SHOW TABLES), DBSQSelectFieldsMySQL (SHOW COLUMNS), DBSQAuthorMySQL (аутентификация).
INSERT INTO testdata VALUES('1','канал','описание','2024-05-01');
UPDATE testdata SET channelname = 'новое' WHERE (id = '1');
PreparedStatement не используется ни в одном запросе; значения подставляются в текст в одинарных кавычках без экранирования.
Важно. Любое строковое поле, включая логин и пароль при аутентификации, является потенциальным вектором SQL-инъекции. Это архитектурно важное ограничение текущей реализации, а не единичная ошибка.
4.3. Соединение и результат
DBSConnection инкапсулирует JDBC-соединение, DBSConnectionMySQL реализует его через DriverManager и единственный Statement (методы connect, closeConnection, applyQuery). DBSResult и DBSResultMySQL отвечают за разбор ResultSet: resultToDataList (слияние с памятью), resultToStrArray и resultToStrMap (списки таблиц и колонок), insertNewData и checkData. Соединение открывается и закрывается на каждую операцию синхронизации или DDL-команду, пул соединений отсутствует.
4.4. Альтернативный бэкенд mqueries
Ветка DBSMQueries / DBSConnectionMQueries / DBSResultJSON объявлена как альтернативный бэкенд, но фактически является заглушкой: DBSConnectionMQueries не переопределяет методы соединения, DBSResultJSON пуст, applyQuery наследуется от DBSConnection и возвращает null. Константа DBSync.typePostgreSQL объявлена, но соответствующей реализации и ветки в фабрике Melda нет: методы createDBSyncDefault и createDBSync для этого типа просто завершаются без действий. Таким образом, реально поддерживается только MySQL.
4.5. Crypto
Класс Crypto реализует симметричное шифрование строк алгоритмом AES/CBC с PKCS5Padding. Ключ и вектор инициализации заданы в коде статическими константами, метод setKey позволяет подменить ключ, после чего первая операция использует переданный ключ, а последующие — ключ текущего пользователя (MUser.getCryptoKey дополняет пароль символом R до восьми знаков и удваивает его). Механизм объявлен, но ни в одной системной модели не включён: вызов setEncrypted(true) в проанализированном коде отсутствует.
5. Автоматическая синхронизация схемы БД (OptDB)
OptDB (189 строк) — механизм, который делает каркас «самонастраивающимся»: схема базы данных выводится из модели данных, описанной в коде, и приводится к ней при запуске приложения. Это одна из двух ключевых особенностей каркаса наряду с метаданными интерфейса.
5.1. Режимы работы
| Константа | Значение | Поведение |
|---|---|---|
| optOnlyCheck | 1 | только диагностика, схема не изменяется (режим по умолчанию) |
| optCreateTables | 2 | создание отсутствующих таблиц |
| optFullUpdate | 3 | создание таблиц и полей, изменение типов колонок |
| optShowDataLists | 4 | диагностическая печать содержимого списков |
5.2. Алгоритм checkDB
- createTables. Для каждого зарегистрированного DataList определяется источник данных по dbSyncName; запрос SHOW TABLES выполняется один раз на источник и кэшируется. Если таблицы с именем списка нет, в режимах 2 и 3 выполняется CREATE TABLE, иначе выводится диагностическое сообщение.
- checkTablesFields. Запрос SHOW COLUMNS; колонка, которая есть в БД, но отсутствует в модели, только диагностируется; поле модели, отсутствующее в БД, добавляется через ADD COLUMN в режиме 3; при несовпадении типа выполняется ALTER TABLE ... MODIFY в режиме 3.
- checkBMSStruct. Создаётся отдельный источник meldadef с жёстко заданными параметрами (127.0.0.1:3306, база meldadef), ему назначается текущий пользователь. Затем OptDataModelsInit регистрирует в этой базе 12 системных списков bms_* (без bms_remote_hosts). После этого перебираются строки bms_screens из meldadef, но тело цикла пусто: сравнение и миграция не выполняются. Для вызова checkBMSStruct требуется существующая база meldadef; реальной синхронизации системных метаданных в текущей версии нет.
- Режим 4. Выводится содержимое списков (showAllTables).
Важно. checkBMSStruct — заготовка: подключение к meldadef и регистрация списков есть, а цикл по bms_screens не содержит ни сравнения, ни миграции. Без базы meldadef этот шаг завершится ошибкой подключения.
Создаваемая таблица состоит из колонки id типа int и колонок, соответствующих полям модели. Первичный ключ, AUTO_INCREMENT, NOT NULL, индексы и внешние ключи не создаются; порядок колонок определяется порядком обхода HashMap и поэтому недетерминирован. Удаление и переименование колонок не поддерживаются, миграция данных и версионирование схемы отсутствуют, DDL-операции не объединяются в транзакцию.
5.3. Итоговая характеристика
Реализован аддитивный механизм миграции «модель → схема»: создание таблиц и колонок, изменение типов. Такой механизм достаточен для прототипирования и для быстро меняющейся предметной области, но не заменяет промышленные системы миграций: он не хранит историю версий, не поддерживает откат и не гарантирует атомарность изменений.
6. Системные метаданные (bms_*)
Тринадцать системных моделей пакета datamodelinit.defmodels описывают сам каркас и хранятся в тех же таблицах, что и прикладные данные. Это делает систему рефлексивной: чтобы добавить экран, достаточно добавить строки в bms_screens и bms_scr_components, а чтобы добавить пользователя — строку в bms_users. Шесть таблиц (bms_screens, bms_scr_components, bms_forms, bms_form_groups, bms_form_elements, bms_filters) образуют модель представления интерфейса.
| Модель (DataList) | Назначение | Ключевые поля |
|---|---|---|
| bms_users | пользователи | ulogin, upass, uname, usecname, usurname, position, ugroup |
| bms_user_groups | группы пользователей | gname |
| bms_user_subordinates | подчинённость (объявлена, не используется) | muser (руководитель), msubuser (подчинённый) |
| bms_access_rules | правила доступа к меню и экранам | mgroup, muser, allowvmenu, allowvscreen |
| bms_access_list_rules | правила по спискам (объявлены, не используются) | mgroup, muser, dlistname, allowview, allowadd, allowchange |
| bms_screens | экраны | name, title |
| bms_scr_components | компоненты экранов | screen, name, type, title, align, linkedlist, options, linkedform |
| bms_forms | формы | name, title, type (BaseForm = 1, MultiForm = 2), linkedlist |
| bms_form_groups | группы полей формы | form, title, align (Vertical = 1, Horisontal = 2 — написание значения в метаданных) |
| bms_form_elements | элементы формы | formg, type, label, fieldname, defvalue, size, viewtype, options |
| bms_filters | фильтры навигаторов и элементов форм | scrnav, formcomp, field, relation, expression, def, logictype |
| bms_gen_props | параметры общего назначения | vermelda («Версия Melda»), verapp («Версия приложения») |
| bms_remote_hosts | удалённые файловые хосты | fhostname, urlhost, protocol |
Поле bms_forms.type объявлено (BaseForm = 1, MultiForm = 2), но FormWindowBuilder его не читает и всегда строит обычную форму; ветка MultiForm через метаданные в текущей сборке недостижима. Таблицы bms_user_subordinates и bms_access_list_rules объявлены, но проверяющим кодом не используются.
7. Подсистема интерфейса
7.1. Component — модель компонента
Component — базовый класс визуального элемента. Он хранит имя (name), JavaFX-панель (pane), ссылку на окно-владелец (sourceWindow), родительский компонент (sourceComponent), список детей (childs) и код выравнивания (align). Метод buildPane создаёт визуальное представление, метод update рекурсивно обходит детей в прямом порядке (for-each по childs) и инициирует инъекцию события onUpdate, метод signalUpdate запускает обновление через окно. Композиция «компонент ↔ JavaFX-узел» и есть механизм, благодаря которому каркас может собирать интерфейс из метаданных: метаданные задают, какой компонент создать, а класс компонента знает, как его отрисовать.
7.2. Окна и многооконность
Window — модель окна, реализующая интерфейс VariableContext; окно содержит корневой компонент и участвует в каскадном обновлении. WindowCollector — контейнер открытых окон: он хранит набор разрешённых окон (allowedWindows), список открытых, кнопки-вкладки WindowButton и активное окно, а метод updateCollector перестраивает панель вкладок и переключает видимость панелей. Многооконность «плоская»: окна — вкладки в одном StackPane, отдельные Stage и модальные окна не используются. Диалоги реализованы классами Dialog и DialogComponent с обработчиком DialogHandler.
7.3. Сборка экрана из метаданных
ScreenWindowBuilder читает строки bms_screens и bms_scr_components и создаёт дерево компонентов. Реестр типов фиксирован: восемь встроенных типов (ScreenLabel, ScreenButton, ListNavigator, TableNavigator, HListNavigator, ComboNavigator, CodeEditor, VideoViewer) плюс пользовательские строители, зарегистрированные через accessUserComponentBuilders. Каждый тип компонента имеет свой ComponentBuilder. Поле bms_scr_components.type — DFChoice: в базе хранится короткий код (lstnav, tabnav и т. п.), а в памяти после загрузки — ключ (ListNavigator); поиск билдера выполняется по ключу.
Важно. В метаданных bms_scr_components.type объявлено 10 допустимых значений: перечисленные восемь плюс Calendar и ReviewView. Билдеров для Calendar и ReviewView нет: screenComponentBuilders.get(type) возвращает null, и при построении экрана с таким типом возникает NullPointerException без диагностического сообщения.
Из метаданных извлекаются: тип компонента, его имя, заголовок, зона выравнивания, имя источника данных (linkedlist), строка options и связанная форма (linkedform). Поле options не является универсальным шаблоном отображения: ListNavigator, HListNavigator и ComboNavigator используют его и как список полей в квадратных скобках, и как шаблон строки с подстановками [поле]; TableNavigator — только как список колонок, шаблон к его ячейкам не применяется; CodeEditor и VideoViewer требуют ровно два поля; ScreenLabel и ScreenButton поле options не читают. Вёрстка, стили, внутренняя структура контролов и все тексты заданы в Java-коде. Таким образом, каркас управляет составом экрана, но не его вёрсткой.
7.4. Навигаторы
Навигаторы — основной инструмент доступа к данным. Четыре визуализации работают поверх одного DataList и разделяют общий контракт NavigatorHandler (создание, редактирование, удаление, выбор записи).
| Класс | Визуализация | Особенности |
|---|---|---|
| ListNavigator | ListView | шаблон строки с подстановками [поле]; контекстное меню создания и удаления |
| TableNavigator | TableView | колонки по выбранным полям; сортировка по возрастанию; открытие ссылок |
| HListNavigator | TreeView | иерархия по полю-пути из {поле-пути}; остаток options — шаблон строки |
| ComboNavigator | ComboBox | выбор одной записи, используется в формах |
Связь «мастер — деталь» реализована через переменные окна: выбор строки записывает идентификатор в переменную с именем навигатора, а фильтры других навигаторов подставляют её через синтаксис $имя. Фильтрация опирается на таблицу bms_filters (отношения ==, !=, cn; логика ltAnd/ltOr); дополнительно существует внешний фильтр FilterIn. Сортировка реализована только в TableNavigator и только по возрастанию.
7.5. Формы
Форма строится по схеме «метаданные → клоны полей → транслятор → запись». FormWindowBuilder читает bms_forms, bms_form_groups и bms_form_elements, создаёт BaseForm, наполняет её группами FormGroup и элементами FormElement, а StandardFormTranslator обеспечивает перенос значений: при создании — из клона модели, при редактировании — из копии полей записи. Запись изменяется только по нажатию «Добавить/Изменить» (метод finish), поэтому отмена не требует отката — рабочая копия просто отбрасывается.
В bms_form_elements.type объявлено 10 значений, но FormWindowBuilder создаёт восемь типов элементов: TextInput, BigTextInput, BooleanChecker, ChoiceChecker, DataChecker, DateCheker (в метаданных — DateChecker), TimeInput и MultiDateChecker. PathChecker и MultiDataChecker не реализованы, и строка с таким типом будет проигнорирована. MultiFormElement — не элемент формы, а базовый класс мульти-элементов (наследник FormElement), на котором построен MultiDateChecker. Поля defvalue, size и options в элементах объявлены, но FormWindowBuilder их не читает.
Валидация централизованно не реализована. Базовый метод DataField.checkValue(String) существует: он пытается присвоить значение, возвращает результат setValue и восстанавливает прежнее значение. Однако этот метод не вызывается ни в одном элементе формы и ни в конвейере сохранения; проверки выполняются точечно: TextInput и BigTextInput возвращают прежний текст при неудачном setValue, DFString ограничивает длину, DFInteger и DFMoney разбирают число, DFURL проверяет ссылку, DFHashtegs сверяет метки со справочником. Сообщений об ошибках и подсветки неверных полей нет.
Ветка MultiForm (bms_forms.type = 2) в текущей сборке недостижима: FormWindowBuilder всегда строит FormComponent/BaseForm, а MultiFormComponent нигде не создаётся.
7.6. Меню
Меню строится программно, а не из базы: MenuBuilder — реестр пунктов, DefMenuBuilder добавляет системное меню «BMS Setup» с пунктами Forms, Screens и Users and rules, прикладной разработчик добавляет собственные меню и пункты-экраны. При построении панели меню MeldaUI проверяет право на отображение пункта через MARuleChecker, а при открытии экрана проверка выполняется ещё раз в MeldaMenu. Пункт-инъекция (addMenuInjectEvent) объявлен, но не реализован: конструктор MeldaMenu игнорирует флаг injectOn, а обработчик пункта умеет открывать только экраны.
7.7. Конвейер обновления
Обновление представления централизовано: изменение данных вызывает Component.signalUpdate, тот передаёт сигнал окну, окно — коллектору, коллектор обновляет все открытые окна, и в каждом окне выполняется рекурсивный update с инъекцией onUpdate. Локальных обновлений нет: стоимость обновления пропорциональна числу открытых окон и размеру списков.
8. Подсистема доступа
Пользователь описан классом MUser (логин, пароль, имя, отчество, фамилия, должность, группа, запись DataClass и список личных правил). Группа — классом MUserGroup. Синглтон accessUsers хранит текущего пользователя, справочники пользователей и групп и загружает их методом receiveUsersAndGroups.
Правило доступа MAccessRule содержит ровно два атрибута: allowViewMenu (строка — заголовок меню) и allowViewScreen (ссылка на запись экрана). MARuleChecker реализует белый список: сначала ищет разрешение в правилах группы, затем в личных правилах; разрешение даёт совпадение в любом из наборов. Прав на списки данных, записи, поля и операции нет; объявленная таблица bms_access_list_rules не используется ни одним проверяющим кодом. Для полноценной ролевой модели, например для LMS с ролями студента, преподавателя и администратора, этого недостаточно.
Практическое ограничение. Если в bms_users.ugroup не выбрана группа, DFData возвращает null, и при загрузке пользователей конструктор MUserGroup разыменовывает null; кроме того, MARuleChecker вызывает getUserGroup().getRules() без проверки на null. В результате вместо диагностического сообщения возникает NullPointerException.
9. Точки расширения
Расширение выполняется без изменения ядра за счёт обнаружения аннотированных классов в фиксированных пакетах прикладного проекта.
| Точка | Механизм | Что позволяет |
|---|---|---|
| Модель данных | DataModel + DataModelsInit.listInit, аннотация @MeldaUserDMInit | новые списки и таблицы; схема синхронизируется OptDB |
| Меню | MenuBuilder, аннотация @MeldaMenuBuilder | собственные меню и пункты экранов |
| Компонент экрана | Component + ComponentBuilder, @MeldaUserComponentBuilder | новый тип в bms_scr_components.type |
| Поведение | InjectMethod, @MeldaInjectMethod | врезка в события onUpdate, onClick, onSelectRow, colorRow |
| Окна | наследование Window + WindowCollector.openWindow | собственные окна вне метаданных |
| Обработчики | NavigatorHandler, CalendarPaneHandler | реакция на выбор и действия |
| Шифрование | DataList.setCryptoKey + DFString.setEncrypted | шифрование строковых полей (механизм объявлен, но не включён) |
Механизм обнаружения реализован классом accessReflect: он получает поток ресурса каталога пакета через ClassLoader.getSystemClassLoader().getResourceAsStream, отбирает имена с расширением .class, загружает классы, сравнивает строковое представление первой аннотации класса с литералом и создаёт экземпляр через первый публичный конструктор. Перечисление работает при распакованной файловой раскладке classpath; при упаковке приложения в JAR каталог пакета через classloader не перечисляется, поэтому точки расширения не обнаруживаются. Порядок обхода также не гарантирован.
Совет. Для поставки приложения в JAR нужен иной механизм обнаружения — например, индекс аннотированных классов, формируемый при сборке.
Инъекции — главная точка расширения поведения. accessInjects хранит список InjectMethod и при каждом событии вызывает те, у которых совпали три признака: имя окна, имя компонента и имя события. Набор событий фиксирован четырьмя строками (onUpdate, onClick, onSelectRow, colorRow); инъекций для форм и жизненного цикла окон нет.
10. Переменные и календарь
Variable и accessVars образуют простейшее глобальное хранилище «ключ — строка». Интерфейс VariableContext реализуют WindowCollector (контекст #имя) и Window (контекст $имя); изменение переменной запускает каскад updateContextWithout, который обновляет все окна, кроме компонента-источника. Механизм обеспечивает связывание компонентов без прямых ссылок, но не имеет типов, пространств имён и очистки, поэтому состояние накапливается в течение сеанса.
Календарная подсистема включает TimeMoment (изменяемая дата и время с русским форматированием), TimeBlock (интервал) и SCalendar (месячная сетка). Она пригодна как примитив выбора даты, но не является моделью расписания: нет учёта високосных лет, повторяемости, часовых поясов и проверки коллизий; TimeBlock в составе каркаса не используется.
11. Жизненный цикл приложения
Последовательность запуска жёстко зашита в Melda.init и критична для работоспособности: нарушение порядка приводит к NullPointerException или к потере метаданных.
- Проверка текущего пользователя; при его отсутствии показывается экран авторизации, и init завершается.
- dataModelsInit: регистрация системных моделей (DefDataModelsInit), затем пользовательских (по аннотации @MeldaUserDMInit), затем добавление списков в модель.
- Регистрация пользовательских строителей компонентов до загрузки данных — иначе строки bms_scr_components не отобразятся на классы; в MeldaUI.build регистрация выполняется повторно.
- Режим отладки БД: при включённом optDBDebugMode выполняется OptDB.checkDB, после чего инициализация завершается.
- accessDataRegistry.updateData — загрузка данных по всем источникам, кроме meldadef.
- accessUsers.receiveUsersAndGroups и receiveRules — загрузка пользователей, групп и правил.
- accessInjects.buildInjects — обнаружение инъекций.
- meldaUI.start — построение меню, панели меню и контейнера окон.
12. Ограничения текущей реализации и технический долг
Раздел фиксирует расхождения между архитектурным замыслом и реализацией. Эти сведения необходимы для корректной интерпретации результатов апробации и для планирования развития каркаса.
| Подсистема | Ограничение | Приоритет |
|---|---|---|
| Персистентность | нет транзакций; частичный сбой оставляет БД и память рассогласованными | высокий |
| Безопасность | SQL собирается конкатенацией, PreparedStatement не используется; логин и пароль подставляются в текст запроса | высокий |
| Аутентификация | пароль bms_users.upass хранится и сравнивается в открытом виде и одновременно служит паролем подключения к MySQL | высокий |
| Производительность | полная загрузка SELECT * и слияние O(n²); линейный поиск по id; отсутствие индексов и пула соединений | высокий |
| Идентификация | идентификаторы генерирует приложение, а не СУБД; в DDL нет PRIMARY KEY и AUTO_INCREMENT | средний |
| Миграция схемы | аддитивная, без удаления и переименования колонок, без ключей, индексов и версионирования; checkBMSStruct — заготовка | средний |
| Модель прав | только меню и экраны; прав на данные, записи и поля нет | средний |
| Завершённость | DFMultidata, DFPoint, mqueries, шифрование полей, MultiForm, checkBMSStruct — заготовки | средний |
| Потокобезопасность | синглтоны без синхронизации, общее соединение, запросы в потоке JavaFX | средний |
| Локализация | все тексты в коде, механизм переводов отсутствует | низкий |
| Диагностика | сообщения выводятся в stdout, уровней и файлового журнала нет | низкий |
Перечисленные ограничения носят инженерный, а не концептуальный характер: они не затрагивают архитектурную идею «модель данных в коде — представление в данных — схема БД из модели», но определяют границы применимости текущей версии (однопользовательская настольная система, умеренные объёмы данных, доверенный контур).
Приложение А. Инвентаризация кодовой базы
Ниже приведена сводная инвентаризация основного кода по пакетам. Значения получены подсчётом строк в исходных файлах, включая пустые строки.
| Пакет | Файлов | Строк |
|---|---|---|
| MELDAVX (корень) | 3 | 388 |
| annotations | 4 | 33 |
| calendar | 3 | 303 |
| datacmds | 4 | 181 |
| datamodel | 6 | 576 |
| datamodel.datafields | 16 | 1 589 |
| datamodelinit | 3 | 103 |
| datamodelinit.defmodels | 13 | 376 |
| dbsyncs | 7 | 715 |
| dbsyncs.mqueries | 3 | 28 |
| dbsyncs.mysql | 3 | 393 |
| dbsyncs.mysql.queries | 11 | 315 |
| injects | 1 | 49 |
| reflect | 1 | 138 |
| users | 5 | 315 |
| usrcomponents | 1 | 97 |
| vars | 3 | 113 |
| windowmodel (+ подпакеты) | 76 | 5 441 |
| Итого | 163 | 11 153 |
Итого: 163 файла и 11 153 строки основного кода; непустых строк — 9 035. Тестовое приложение — 6 файлов, 156 строк.
Примечание. Значения «8 типов компонентов экрана» и «8 типов элементов формы» в таблице 2 относятся к реализованным билдерам; в метаданных bms_scr_components.type и bms_form_elements.type объявлено по 10 значений (Calendar и ReviewView; PathChecker и MultiDataChecker не реализованы).