BeanExplorer5 API — различия между версиями

Версия 14:36, 25 ноября 2015

Backend

BeanExplorer5 проект - это OSGi бандл, поддерживающий расширения через plugin.xml.

При сборке BeanExplorer5 проекта он воспринимается как OSGi бандл, поэтому у него должен быть манифест META-INF/MANIFEST.MF. В этом манифесте указывается, от каких бандлов зависит данный бандл. Основные классы API находятся в бандле com.beanexplorer.be5, поэтому его необходимо указать в манифесте.

Помимо этого в структуру BeanExplorer5 проекта входит plugin.xml, в котором возможно объявлять свои компоненты, используя точку расширения com.beanexplorer.be5.component, которая объявлена в бандле com.beanexplorer.be5. Пример объявления компонента:

<extension point="com.beanexplorer.be5.component">
  ...
  <component
    class="com.beanexplorer.enterprise.components.Menu"
    id="menu"
    name="Menu">
  </component>

Указанный класс должен реализовывать интерфейс Component:

package com.beanexplorer.enterprise.components;

public interface Component {
  void generate(ComponentParameters parameters);
}

com.beanexplorer.be5.component - это единственная точка расширения BeanExplorer5, она позволяет регистрировать свои backend компоненты, которые будут доступны следующим URL:

//domain/app/main/:componentId
//domain/app/main/:componentId/:any/:path

Например:

http://localhost:8080/biostore_be5/main/menu
http://localhost:8080/biostore_be5/main/menu/withIds

При запросе к веб-приложению по этим запросам будет создан новый экземпляр компонента и вызван его метод generate. Для того, чтобы узнать путь после имени компонента (:any/:path), нужно вызвать метод parameters.getRequestUri(). В случае пустого пути возвращается пустая строка. В случае наличия пути, он возвращается без начального слеша.

Основные интерфейсы и классы API

• Component - главный интерфейс, который должны реализовывать BE5 компоненты. Поскольку проще всего общаться с frontend посредством пересылки JSON, существуют абстрактные классы, которые упрощают написание таких компонентов:
  • JsonComponent - при наследовании этого класса необходимо только реализовать один метод, возвращающий строку, представляющую собой JSON.
  • NetSfJsonComponent - при наследовании этого класса необходимо только реализовать один метод, возвращающий net.sf.json.JSONObject.
• ComponentParameters - всё, что необходимо компоненту. Если необходимо что-то ещё, то либо мы что-то забыли или не предусмотрели (и об этом непременно стоит сообщить нам), либо вы неправильно используете API BeanExplorer5. К чему возможно доступиться из этого компонента:
  • Project - BE4 проект.
  • Meta - полезные методы для работы с BE4 проектом.
  • UserService - работа с сессиями, ролями, выбором языка.
  • ResponseService - формирование текстового ответа. Необходимо только для абстрактных компонентов, обеспечивающих обмен текстовыми сообщениями в каком-нибудь формате (JSON, XML и т.п.).
  • HttpServletRequest и HttpServletResponse - предполагается, что в обычной ситуации они не используются. Необходимы только для реализации абстрактных компонентов, обеспечивающих работу с каким-нибудь протоколом на низком уровне. Для обмена текстом достаточно ResponseService.

Обратите внимание на то, что другие классы не являются частью API, в т.ч. класс Be5 и классы, связанные с реализацией конкретных компонентов.

Частью API также являются соглашения о том, какие данные возвращают компоненты, поскольку эти соглашения используются обмена сообщениями между frontend и backend частями компонентов. Исключением являются соглашения о том, какие данные возвращают компоненты, описанные в разделе REST API.

Frontend

Компоненты BE5 на frontend - это React.js компоненты.

Компоненты подключаются через SystemJS, при этом используется синтаксис ES2015 или метод define.

import Component from 'components/component';

define([ 'components/component' ], function(Component) {
  // use(Component)
  // ...
  return {};
});

Кнопки и ссылки на компоненты (в частности запросы и формы) в BE5 не должны писаться вручную.

Не всё, что находится в проекте be5-frontend, является частью API.

Основные части API

• be5 - ядро frontend. Функции, являющиеся частью API:
  • be5.net.request: function(path, params, success, failure) - делает асинхронный POST запрос к вашему backend компоненту (path - componentId/any/path).
  • be5.registerAction: function(actionName, fn) - регистрирует действие, которое будет вызвано при клике по кнопке или ссылке. Вызов действия является следствием смены hash url, при этом адрес разбирается на позиционные и именованные параметры. В зарегистрированную функцию передаются все позиционные параметры, за которыми идёт объект с именованными параметрами. Именованными параметрами считаются части URL, которые содержат символ '=', а позиционными считаются все остальные.
  • be5.ui.registerDocumentType: function(type, creator) - регистрирует новый вид документа. Функция, переданная вторым параметром в registerDocumentType обычно вызывает React.createElement и возвращает результат вызова. Результат будет помещён в стандартное для проекта место отображения документа. На данный момент на backend невозможно добавлять свои виды документов, но документ возможно создать посредством вызова be5.ui.recreateDocument.
  • be5.ui.recreateDocument - пересоздаёт документ. В качестве аргумента передаётся объект с двумя полями: type и value. Первое указывает тип документа, второе - значение документа, которое интерпретируется обработчиком документа, зарегистрированным посредством вызова be5.ui.registerDocumentType.
  • be5.ui.createDocument - похож на be5.ui.recreateDocument, однако позволяет встраивать документы в произвольное место страницы. Полезно, если тип документа заранее неизвестен.
  • be5.load.css(path) - подгружает CSS динамически, это необходимо во frontend компонентах, которым нужен CSS. path - путь к файлу CSS, например css/menu.css.
  • be5.messages - объект с локализованными сообщениями (русский и английский язык).

Другой способ определения действий

Вы также можете определить действие неявным способом не вызывая be5.registerAction. Для этого создаётся файл с именем /actions/yourAction.js, который определяет AMD модуль посредством метода define. Объявдяемым элементом в этом модуле является функция, которая используется так же, как и функция, регистрируемая вызовом be5.registerAction, однако при этом подгрузка компонента произойдёт лениво - при первом его использовании.

REST API