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

Техническое описание фреймворка Melda

Настоящий документ — справочное описание внутреннего устройства каркаса Melda, подготовленное по результатам статического анализа исходного кода пакета MELDAVX (Java и JavaFX). Версия документа 1.0. Назначение — служить справочником по архитектуре, подсистемам и текущей реализации каркаса; приёмы прикладной разработки вынесены в отдельное руководство. Смежные страницы раздела: руководство по разработке, загрузки и обзор проекта MeldaVX.

1. Общие сведения о каркасе

1.1. Назначение

Melda — встраиваемый каркас (библиотека) для быстрой разработки информационных систем, управляемых данными. Каркас не является готовым приложением: он подключается к прикладному проекту и берёт на себя четыре задачи:

  1. описание модели данных и её отображение на схему реляционной базы;
  2. загрузку и сохранение данных без написания SQL прикладным разработчиком;
  3. построение пользовательского интерфейса по метаданным, хранящимся в базе;
  4. разграничение доступа на уровне меню и экранов.

Прикладной разработчик описывает предметную область классами-наследниками DataModel (набор типизированных полей) и подключает их к источнику данных; дальнейшее поведение системы — создание таблиц, экранов, навигаторов, форм — определяется метаданными, которые можно изменять без пересборки приложения.

1.2. Технологический стек и зависимости

Каркас реализован на Java и JavaFX. Внешние зависимости сведены к минимуму: стандартная библиотека JDK (java.util, java.io, java.sql, javax.crypto), JavaFX (графический интерфейс) и библиотека RichTextFX (org.fxmisc.richtext), используемая только компонентом CodeEditor. Фреймворков внедрения зависимостей, ORM, контейнеров сервлетов и систем логирования в составе каркаса нет.

Таблица 1. Внешние зависимости каркаса
Зависимость Назначение в каркасе Масштаб использования
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).

Таблица 2. Метрики кодовой базы
Показатель Значение
Файлов 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 пакетов; ниже пакеты верхнего уровня показаны вместе с вложенными там, где это важно для понимания структуры.

Таблица 3. Назначение пакетов
Пакет Файлов Строк Назначение
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 состоит в том, что в системе одновременно существуют три модели, описанные разными средствами и играющие разные роли.

  1. Модель данных (в коде). Класс-наследник DataModel содержит список прототипов полей DataField, созданных строителем DFB. Модель типизирована средствами языка, проверяется компилятором и участвует в рефакторинге.
  2. Модель представления (в базе данных). Экраны, компоненты экранов, формы, группы полей, элементы форм и фильтры хранятся строками в шести таблицах: bms_screens, bms_scr_components, bms_forms, bms_form_groups, bms_form_elements, bms_filters. Изменение этих строк меняет интерфейс без пересборки приложения.
  3. Системная модель (самоописание). Пользователи, группы, правила доступа и сами метаданные интерфейса описаны теми же средствами — классами DataModel в пакете datamodelinit.defmodels. Каркас применяет свой механизм метаданных к собственным метаданным, то есть модель рефлексивна.

Такое разделение — ключевое архитектурное решение: типизированная часть (структура данных) остаётся в языке программирования, а изменяемая часть (состав и параметры экранов) выносится в данные.

2.2. Слои

Таблица 4. Слои каркаса и их ответственность
Слой Ключевые классы Ответственность
Прикладной наследники 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 и особенности реализации.

Таблица 5. Типы полей и их отображение на SQL
Тип Назначение 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. Режимы работы

Таблица 6. Режимы работы OptDB
Константа Значение Поведение
optOnlyCheck 1 только диагностика, схема не изменяется (режим по умолчанию)
optCreateTables 2 создание отсутствующих таблиц
optFullUpdate 3 создание таблиц и полей, изменение типов колонок
optShowDataLists 4 диагностическая печать содержимого списков

5.2. Алгоритм checkDB

  1. createTables. Для каждого зарегистрированного DataList определяется источник данных по dbSyncName; запрос SHOW TABLES выполняется один раз на источник и кэшируется. Если таблицы с именем списка нет, в режимах 2 и 3 выполняется CREATE TABLE, иначе выводится диагностическое сообщение.
  2. checkTablesFields. Запрос SHOW COLUMNS; колонка, которая есть в БД, но отсутствует в модели, только диагностируется; поле модели, отсутствующее в БД, добавляется через ADD COLUMN в режиме 3; при несовпадении типа выполняется ALTER TABLE ... MODIFY в режиме 3.
  3. checkBMSStruct. Создаётся отдельный источник meldadef с жёстко заданными параметрами (127.0.0.1:3306, база meldadef), ему назначается текущий пользователь. Затем OptDataModelsInit регистрирует в этой базе 12 системных списков bms_* (без bms_remote_hosts). После этого перебираются строки bms_screens из meldadef, но тело цикла пусто: сравнение и миграция не выполняются. Для вызова checkBMSStruct требуется существующая база meldadef; реальной синхронизации системных метаданных в текущей версии нет.
  4. Режим 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) образуют модель представления интерфейса.

Таблица 7. Системные модели каркаса
Модель (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 (создание, редактирование, удаление, выбор записи).

Таблица 8. Навигаторы каркаса
Класс Визуализация Особенности
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. Точки расширения

Расширение выполняется без изменения ядра за счёт обнаружения аннотированных классов в фиксированных пакетах прикладного проекта.

Таблица 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 или к потере метаданных.

  1. Проверка текущего пользователя; при его отсутствии показывается экран авторизации, и init завершается.
  2. dataModelsInit: регистрация системных моделей (DefDataModelsInit), затем пользовательских (по аннотации @MeldaUserDMInit), затем добавление списков в модель.
  3. Регистрация пользовательских строителей компонентов до загрузки данных — иначе строки bms_scr_components не отобразятся на классы; в MeldaUI.build регистрация выполняется повторно.
  4. Режим отладки БД: при включённом optDBDebugMode выполняется OptDB.checkDB, после чего инициализация завершается.
  5. accessDataRegistry.updateData — загрузка данных по всем источникам, кроме meldadef.
  6. accessUsers.receiveUsersAndGroups и receiveRules — загрузка пользователей, групп и правил.
  7. accessInjects.buildInjects — обнаружение инъекций.
  8. meldaUI.start — построение меню, панели меню и контейнера окон.

12. Ограничения текущей реализации и технический долг

Раздел фиксирует расхождения между архитектурным замыслом и реализацией. Эти сведения необходимы для корректной интерпретации результатов апробации и для планирования развития каркаса.

Таблица 10. Ограничения по подсистемам и приоритет устранения
Подсистема Ограничение Приоритет
Персистентность нет транзакций; частичный сбой оставляет БД и память рассогласованными высокий
Безопасность SQL собирается конкатенацией, PreparedStatement не используется; логин и пароль подставляются в текст запроса высокий
Аутентификация пароль bms_users.upass хранится и сравнивается в открытом виде и одновременно служит паролем подключения к MySQL высокий
Производительность полная загрузка SELECT * и слияние O(n²); линейный поиск по id; отсутствие индексов и пула соединений высокий
Идентификация идентификаторы генерирует приложение, а не СУБД; в DDL нет PRIMARY KEY и AUTO_INCREMENT средний
Миграция схемы аддитивная, без удаления и переименования колонок, без ключей, индексов и версионирования; checkBMSStruct — заготовка средний
Модель прав только меню и экраны; прав на данные, записи и поля нет средний
Завершённость DFMultidata, DFPoint, mqueries, шифрование полей, MultiForm, checkBMSStruct — заготовки средний
Потокобезопасность синглтоны без синхронизации, общее соединение, запросы в потоке JavaFX средний
Локализация все тексты в коде, механизм переводов отсутствует низкий
Диагностика сообщения выводятся в stdout, уровней и файлового журнала нет низкий

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

Приложение А. Инвентаризация кодовой базы

Ниже приведена сводная инвентаризация основного кода по пакетам. Значения получены подсчётом строк в исходных файлах, включая пустые строки.

Таблица 11. Сводка по пакетам
Пакет Файлов Строк
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 не реализованы).