Манифесты плагина¶
JAR-файлы плагинов содержат манифест плагина — файл верхнего уровня с названием metabase-plugin.yaml. При запуске Glarus BI перебирает каждый JAR-файл в каталоге плагинов и ищет манифест в каждом из них. Этот манифест сообщает Glarus BI, что реализует плагин и как его инициализировать.
Пример манифеста¶
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.
Ленивая загрузка¶
Драйвер в примере выше указан как lazy-load: true, что означает, что несмотря на то что упомянутая выше реализация метода создаётся при запуске Glarus BI, Glarus BI не будет инициализировать драйвер до тех пор, пока кто-то не попытается подключиться к базе данных, использующей этот драйвер.
Вы можете (но не обязаны) установить для драйвера значение lazy-load: false, но это увеличит время запуска Glarus BI и займёт больше памяти.
Инициализация плагина¶
Glarus BI автоматически инициализирует плагины по мере необходимости. Инициализация происходит примерно так: Glarus BI добавляет драйвер в classpath, затем по порядку выполняет раздел init манифеста плагина. В примере манифеста выше есть два шага: шаг load-namespace и шаг register-jdbc-driver:
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».
Регистрация драйверов 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 скриптов сборки драйвера.
Поместите JAR, который вы создали, в каталог /plugins, и всё готово.
Справочник по манифесту плагина Glarus BI¶
Вот пример манифеста плагина с комментариями, который поможет вам начать писать свой собственный.
# Основная информация о драйвере для пользователя находится под ключом 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
Дополнительная информация¶
Реализация мультиметодов для вашего драйвера.