Пример OSGi-bundle для NCALayer

(Пример с Common Invoker)

Модуль NCALayer (OSGi bundle) - подписанный jar, в манифесте которого имеются свойства:

• Bundle-SymbolicName - символическое имя (уникальный идентификатор)
• Bundle-Name - наименование
• Bundle-Version - версия
• Export-Package - список пакетов, к которым можно дать доступ для других модулей. Указывать нужно полное название пакета, без wildcard.
• Import-Package - список пакетов, к которым нужен доступ. Основные экспортируемые пакеты определяются в syspkgs ядра NCALayer. Другие пакеты экспортируются модулями NCALayer. Указывать нужно полное название пакета, без wildcard. Неправильно - javax.xml.*, правильно - javax.xml.parsers
• Bundle-Activator - полное наименование класса, реализующего интерфейс org.osgi.framework.BundleActivator. На данный момент активатор нужен для регистрации сервисов при запуске модуля.

Сервис (класс, реализующий kz.gov.pki.osgi.layer.api.ModuleService) содержит основную логику модуля. При регистрации сервиса необходимо задать уникальное значение module, по которому можно к нему обратиться. module не зависит от Bundle-SymbolicName и может отличаться, так как в одном модуле может быть реализовано более одного сервиса.

Рекомендуется использовать осмысленные значения. Например:

• Bundle-SymbolicName: kz.yourcompany.yourbundle
• module: kz.yourcompany.yourbundle.yourservice

Данные передаются в формате JSON. Например, запрос к модулю из примера выглядит следующим образом:

{
    "module": "kz.gov.pki.SampleBundle",
    "method": "salemAit",
    "args": {
        "username": "Jay"
    }
}

На что можно получить следующий ответ:

{
    "success": true,
    "body": {
        "result": "Salem, Jay"
    }
}

Общедоступные сервисы

• LogService - сервис логирования для записи событий в общий журнал (ncalayer.log).
• NCALayerService - сервис может предоставить экземпляр зарегистрированного KalkanProvider.
• Запрос для получения списка установленных модулей с версиями:

  {
      module: "kz.gov.pki.ncalayerservices.accessory",
      method: "getBundles"
  }
  

  Ответ:

  {
      "kz.gov.pki.api.layer.NCALayerServices": "0.5.0",
      "kz.gov.pki.osgi.layer.websocket": "0.3.3",
      "kz.gov.pki.kalkan.knca_provider_jce_kalkan": "0.5.0"
  }
  

• Запрос для получения списка зарегистрированных сервисов:

  {
      module: "kz.gov.pki.ncalayerservices.accessory",
      method: "getServices”
  }
  

  Ответ:

  {
      "services": [
          "kz.gov.pki.cms.CMSSignUtil",
          "kz.gov.pki.ncalayerservices.accessory"
      ]
  }
  

Тестирование нового модуля

Для начала нужно запросить у НУЦ РК ncalayer.der с данными модуля для локального тестирования. Для этого необходимо предоставить следующие данные о модуле:

• Bundle-SymbolicName
• сертификат подписи кода
• наименование

После получения ncalayer.der нужно заменить оригинальный файл, расположенный в домашней директории NCALayer. Это позволит устанавливать и обновлять свой модуль локально без ограничений, путем копирования jar в папку bundles. При этом NCALayer не сможет запрашивать обновления с интернета. При локальных обновлениях нужно либо повышать Bundle-Version нового jar, либо удалять из папки ncalayer-cache папку старого jar (папка bundleX - где X число, обычно модуль установленный последним имеет наибольшее значение).

Дополнительные возможности

В NCALayer существует возможность установки модуля по запросу при его отсутствии в числе установленных модулей. Данной функцией можно воспользоваться следующим образом:

1. После подключения к NCALayer есть два варианта проверки того, что модуль не установлен. Веб-ресурс:
   • запрашивает список установленных модулей и не находит в полученном списке необходимого модуля
   • вызывает какую-либо функцию модуля и в ответ получает:

     {
         "success": false,
         "errorCode": "MODULE_NOT_FOUND"
     }
     

2. Если модуль не найден, то отправляется запрос на установку необходимого модуля по Bundle-SymbolicName:

   {
       module: "kz.gov.pki.ncalayerservices.accessory", 
       method: "installBundle",
       symname: "kz.yourcompany.yourbundle"
   }
   

3. Пользователь получает сообщение о том, что необходимо установить дополнительный модуль. В случае успешной загрузки модуля, NCALayer попросит разрешения на перезапуск.
4. После перезапуска NCALayer модуль будет готов к использованию.