# Манифесты плагина JAR-файлы плагинов содержат _манифест плагина_ — файл верхнего уровня с названием `metabase-plugin.yaml`. При запуске Glarus BI перебирает каждый JAR-файл в каталоге плагинов и ищет манифест в каждом из них. Этот манифест сообщает Glarus BI, что реализует плагин и как его инициализировать. ## Пример манифеста ```yaml info: name: Glarus BI SQLite Driver version: 1.0.0-SNAPSHOT-3.25.2 description: Allows Glarus BI to connect to SQLite databases. contact-info: name: Toucan McBird address: toucan.mcbird@example.com driver: name: sqlite display-name: SQLite lazy-load: true parent: sql-jdbc connection-properties: - name: db display-name: Filename placeholder: /home/camsaul/toucan_sightings.sqlite required: true init: - step: load-namespace namespace: metabase.driver.sqlite - step: register-jdbc-driver class: org.sqlite.JDBC ``` Раздел `driver` сообщает Glarus BI, что подключаемый модуль определяет драйвер с именем `:sqlite`, который имеет `:sql-jdbc` в качестве родителя. Система плагинов Glarus BI использует эти данные для вызова `driver/register!`. Плагин также перечисляет отображаемое имя и свойства подключения для драйвера, которые система плагинов Glarus BI использует для создания реализаций для `driver/display-name` и `driver/connection-properties`. ## Ленивая загрузка Драйвер в [примере выше](#example-manifest) указан как `lazy-load: true`, что означает, что несмотря на то что упомянутая выше реализация метода создаётся при запуске Glarus BI, Glarus BI не будет инициализировать драйвер до тех пор, пока кто-то не попытается подключиться к базе данных, использующей этот драйвер. Вы _можете_ (но не обязаны) установить для драйвера значение `lazy-load: false`, но это увеличит время запуска Glarus BI и займёт больше памяти. ## Инициализация плагина Glarus BI автоматически инициализирует плагины по мере необходимости. Инициализация происходит примерно так: Glarus BI добавляет драйвер в classpath, затем по порядку выполняет раздел `init` манифеста плагина. В [примере манифеста выше](#example-manifest) есть два шага: шаг `load-namespace` и шаг `register-jdbc-driver`: ```yaml init: - step: load-namespace namespace: metabase.driver.sqlite - step: register-jdbc-driver class: org.sqlite.JDBC ``` ## Загрузка пространств имён Вам нужно будет добавить один или несколько шагов `load-namespace` в манифест вашего драйвера, чтобы сообщить Glarus BI, какие пространства имён содержат реализации вашего метода драйвера. В приведённом выше примере пространство имён — `metabase.driver.sqlite` `load-namespace` вызывает `require` обычным способом, что означает, что он будет загружать другие пространства имен, перечисленные в разделе `:require` его объявления пространства имён по мере необходимости. Если реализации методов вашего драйвера разделены на несколько пространств имен, убедитесь, что они также будут загружены — вы можете либо сделать так, чтобы основное пространство имён обрабатывало их (например, включив их в форму `:require` в объявлении пространства имен), либо путём добавления дополнительных шагов `load-namespace`. Дополнительную информацию о пространствах имён см. в разделе ["Пространства имён Clojure"](https://clojure.org/guides/learn/namespaces). ## Регистрация драйверов JDBC Драйверы, которые под капотом используют драйвер JDBC, также должны будут добавить шаг `register-jdbc-driver`. Причина заключается в том, что Java JDBC `DriverManager` не будет использовать драйверы JDBC, загруженные чем-то другим, кроме системного `ClassLoader`, что фактически означает только то, что `Drivermanager` будет использовать только классы драйверов JDBC, которые упакованы как часть ядра Glarus BI uberjar. Поскольку системный загрузчик классов не позволяет вам загружать путь к классам во время выполнения, Glarus BI использует пользовательский `ClassLoader` для инициализации плагинов. Чтобы обойти это ограничение, Glarus BI поставляется с классом прокси-драйвера JDBC, который может заключать в себе другие драйверы JDBC. Когда Glarus BI вызывает `register-jdbc-driver`, Glarus BI фактически регистрирует новый экземпляр прокси-класса, который перенаправляет вызовы методов фактическому драйверу JDBC. `DriverManager` прекрасно с этим справляется. ## Сборка драйвера Чтобы собрать драйвер в виде JAR-файла плагина, ознакомьтесь с [README скриптов сборки драйвера](https://github.com/metabase/metabase/tree/master/bin/build-drivers.md). Поместите JAR, который вы создали, в каталог `/plugins`, и всё готово. ## Справочник по манифесту плагина Glarus BI Вот пример манифеста плагина с комментариями, который поможет вам начать писать свой собственный. ```yaml # Основная информация о драйвере для пользователя находится под ключом info: info: # Обязательно дайте вашему плагину имя. В будущем оно будет показано # для пользователя на странице администрирования «управления плагинами». name: Glarus BI SQLite Driver # Для согласованности с основным проектом Glarus BI вам # следует использовать семантическое управление версиями. Неплохо было бы включить # версию его основной зависимости (например, драйвера JDBC), когда # используется часть «патча» версии, в этом случае мы сможем # обновить зависимости и отразить это в номере версии # # На данный момент основные модули Glarus BI должны иметь версию # 1.0.0-SNAPSHOT-x до выхода версии 1.0 и заморозки версии API для плагинов version: 1.0.0-SNAPSHOT-3.25.2 # Опишите, что делает ваш плагин. В настоящее время не используется, но в # в будущем мы можем использовать это описание на странице администрирования плагинов. description: Позволяет Glarus BI подключаться к базам данных SQLite. # Вы можете перечислить любые зависимости, необходимые плагину, указав # список зависимостей. Если все зависимости не соблюдены, плагин # не будет инициализирован. # # Зависимостью может быть либо "класс", либо (в будущем) "плагин" dependencies: # Зависимость класса проверяет, доступен ли данный класс. Класс при этом не инициализируется;    # Glarus BI откладывает инициализацию, # пока не потребуется использовать драйвер. # Не используйте это для классов, которые поставляются как часть самого плагина; # используйте его только для внешних зависимостей. - class: oracle.jdbc.OracleDriver # Вы можете дополнительно добавить сообщение, которое будет отображаться # в логах и возможно в будущем на странице управления плагином message: > Glarus BI requires the Oracle JDBC driver to connect to JDBC databases. See https://metabase.com/docs/latest/administration-guide/databases/oracle.html for more details # Зависимость 'plugin' проверяет, доступен ли данный плагин. # Значением для 'plugin' является то, что этот плагин имеет в качестве 'name:' # убедитесь в точном соответствии. # # Если зависимость недоступна при первой загрузке этого модуля, # попытка загрузки будет повторена позже, после загрузки дополнительных модулей. Это означает, что система будет # работать так, как мы ожидаем, даже если, скажем, мы сначала пытаемся загрузить # драйвер BigQuery *до* загрузки его зависимости, общего драйвера Google. # Загрузив после этого общий драйвер Google, Glarus BI обнаружит, что зависимость драйвера BigQuery # теперь выполнена и инициализируют плагин. # # В будущем мы также добавим ограничения по версиям - plugin: Glarus BI SQLHeavy Driver # Если плагин добавляет драйвер, он должен определить блок driver: # # Чтобы определить несколько драйверов, вы можете передать список словарей. # Множественные драйвера в настоящее время все ещё должны использовать один и тот же набор # зависимостей и шагов инициализации. Таким образом, регистрация нескольких драйверов является наиболее # полезной в случае использования небольших вариаций одного и того же драйвера или включения абстрактного # родительского драйвера. Обратите внимание, что шаги инициализации будут выполняться один раз для каждого драйвера # который загружается. Это может привести к дублированию зарегистрированных экземпляров драйвера в DriverManager # Это не самый оптимальный вариант, но он вполне рабочий. driver: # Имя драйвера; соответствует используемому ключевому слову (например, :sqlite) # в кодовой базе name: sqlite # Красивое отображаемое имя, которое будет показано администраторам при подключении к базе данных display-name: SQLite # Можно ли отложить загрузку этого драйвера до первой # попытки подключения к базе данных этого типа. По умолчанию: true. # установите значение false, только если это абсолютно необходимо. lazy-load: true # Родительский драйвер, если есть. parent: sql-jdbc # В качестве альтернативы вы можете указать список родителей для драйвера, если их # больше одного: parent: - google - sql # Является ли этот драйвер абстрактным. По умолчанию: false abstract: false # Список атрибутов подключения, для использования в этом драйвере connection-properties: # Свойства подключения могут быть одним из значений по умолчанию, найденных в # metabase.driver.common, перечисленные по имени: - dbname  - host # Или полная карта для пользовательского варианта. Полная схема для пользовательского # варианта может быть найдена в metabase.driver. - name: db display-name: Filename placeholder: /home/camsaul/toucan_sightings.sqlite required: true # Наконец, вы можете использовать merge: для объединения нескольких словарей. Это # полезно для переопределения некоторых свойств в одном из значений по умолчанию. - merge: - port - placeholder: 1433 # Шаги для инициализации плагина. Для драйверов с отложенной загрузкой это # откладывается до инициализации драйвера при первом подключении # к базе данных init: # load-namespace сообщает Glarus BI, что требуется пространство имён из JAR. # вы можете делать любые операции внутри этого пространства имён - step: load-namespace namespace: metabase.driver.sqlite # register-jdbc-driver указывает Glarus BI необходимость зарегистрировать драйвер JDBC, который # будет использоваться этим драйвером. (Он фактически регистрирует прокси, # так как DriverManager не разрешает загрузку драйверов # другим загрузчиком классов, отличным от того которым он был загружен # Не беспокойтесь об этом, но знайте что для # драйверов на основе JDBC, вам нужно указать здесь свою зависимость) - step: register-jdbc-driver class: org.sqlite.JDBC ``` ## Дополнительная информация [Реализация мультиметодов](multimethods.md) для вашего драйвера.