Редактор схем точек расширения

Редактор схемы точек расширения можно открыть двумя способами: как побочный результат создания точки расширения или открыв схему для существующей точки расширения.   Принято, что имена схем совпадают с ИД точки расширения и имеют расширение файла .exsd. Они помещаются в каталог schema дерева каталогов модулей.  

При создании новой точки расширения в PDE будет создан также начальный файл схемы, который будет открыт в редакторе схемы. Схему можно задать сразу же или отложить ее создание на потом. Полная схема точки расширения используется PDE для автоматических операций поддержки пользователей вашей точки расширения.

Редактор схем PDE использует те же концепции, что и редактор манифеста модуля.   Он содержит две страницы форм и одну - для исходного текста.   Поскольку схема XML изложена очень подробно, и ее трудно читать в виде исходного текста, как правило следует использовать страницы форм при редактировании.   Страница исходных текстов полезна для чтения получающегося кода.

Пример: Создание схемы для точки расширения "Примеры анализаторов"

Ранее мы создали точку расширения "Примеры анализаторов" и начальную схему. Откроем схему, зайдя в каталог schema проекта и дважды щелкнув на файле parsers.exsd.  Откроется редактор схемы.

Выполним следующие задачи:

  1. Определить элементы и атрибуты XML для точки расширения.
  2. Определить грамматику (модель информации).
  3. Создать фрагменты документации, которые будут включены в справочный документ.

Каждая схема точки расширения начинается с объявления элемента "extension".   Добавим новый элемент XML "parser."

  1. Нажмите кнопку Создать элемент в разделе Элементы точки расширения.
  2. Перейдите в панель Свойства и измените его имя с "New_Element" на "parser"
  3. Пока элемент выбран, нажмите еще раз Создать атрибут. Будет создан "new_attribute" как вложенный элемент. Измените его имя на "id" и параметр use задайте равным "required" в окне свойств.
  4. В этом окне нажмите кнопку панели инструментов "Создать копию атрибута". В результате будет создана копия этого атрибута.  Это полезная функция, с помощью которой можно быстро задать все атрибуты прямо в этом окне.
  5. Измените имя нового атрибута на "name."
  6. Создайте еще одну копию атрибута. Теперь назовите его "class."  Этот атрибут будет задавать полное имя класса Java, который должен реализовывать конкретный интерфейс Java. Укажите его, чтобы впоследствии PDE могла с ним работать. Измените kind с "string" на "java."  Задайте свойство basedOn равным com.example.xyz.IParser.  Этот интерфейс еще не существует, но мы его создадим позже.

Редактор схемы примет следующий вид:

Редактор схемы точки расширения - страница Определения

Добавим несколько атрибутов, выбирая их значения из списка.   Это означает, что нам нужно создать ограничение - перечисление типа string.  Кроме того, зададим значение по умолчанию для атрибута.

  1. Когда элемент "parser" выбран, нажмите кнопку Создать атрибут. Укажите его имя как "mode".
  2. Щелкните на ячейке свойства "restriction", чтобы открыть окно для ввода ограничений.  
  3. Измените тип ограничения с "none" на "enumeration."
  4. Добавьте три варианта: "never" "always" и "manual."  Это будут три гипотетических режима расширения анализатора.

Окно ограничений примет следующий вид:

Окно диалога Ограничения типов

Закрыв окно, измените атрибут "use" на "default" и атрибут "value" на "always."  Тем самым будет задано значение по умолчанию.   При вводе значения строка состояния отображает ошибку, поскольку допустимые значения ограничены тремя вариантами перечисления. При окончании ввода сообщение об ошибке исчезнет, поскольку "always" - допустимое значение.

Задав все элементы, определим грамматику. Мы хотим, чтобы элемент "extension" мог иметь любое число потомков - элементов "parser". 

  1. Выберите элемент "extension". Его начальная модель информации показана как пустой составитель последовательности.
  2. Выберите составитель последовательности и в выпадающем меню выберите Создать->Справочник->parser. Ссылка на анализатор будет добавлена в составитель последовательности.
  3. Количество ссылок по умолчанию указано как [1,1], то есть может быть только один элемент "parser". Это не совсем то, что нам нужно. Выберем ссылку "parser" и зададим значение maxOccurs равным "без ограничений."

После определения грамматики ниже будет показан примерный вид DTD для выбранного элемента.  Эта информация служит подсказкой для разработчиков, которые пока что привыкли работать с DTD, а не со схемами XML.

Редактор схемы точки расширения - грамматика элемента

Задав элементы, атрибуты и грамматику, займемся документацией для точки расширения. Существует два типа фрагментов документации схемы:

Левый тип фрагмента показан на странице Определения манифеста схемы. Выбирая элементы и атрибуты, вы можете вводить краткий текст о них в разделе "Описание". Текст вводится в виде кода HTML (как с Javadoc) и будет скопирован как есть в конечный справочный документ.

  1. Выберите атрибут "id" элемента "parser" и введите следующий текст в редакторе описания:
    уникальное имя, которое будет обозначать данный анализатор.
  2. Выберите атрибут "name" и введите следующий текст:
    локализованное имя, которое будет обозначать данный анализатор в пользовательском интерфейсе
  3. Выберите атрибут "class" и введите следующий текст (с учетом тегов HTML):
    полное имя класса Java, реализующего интерфейс <samp>com.example.xyz.IParser</samp>.
  4. Выберите атрибут "mode" и введите следующий текст:
    необязательный флаг, указывающий, как часто будет выполняться этот экземпляр анализатора (значение по умолчанию - <samp>always</samp>).

Теперь введем краткое описание самой точки расширения. Для этого перейдем на страницу Документация:

  1. Перейдите на вкладку "Обзор". В текстовом редакторе введите следующий текст:

    Эта точка расширения служит для подключения дополнительных анализаторов. Анализаторы в действительности не работают - они здесь описаны лишь как пример схемы точки расширения.

    Нажмите Применить.
  2. Щелкните на вкладке "Примеры" и введите следующий текст:

    Ниже приведен пример использования этой точки расширения:

       <p>
       <pre>
          <extension point="com.example.xyz.parsers">
             <parser
                id="com.example.xyz.parser1"
                name="Анализатор 1"
                class="com.example.xyz.SampleParser1">
             </parser>
          </extension>
       </pre>
       </p>
    

    Нажмите Применить.

  3. Выберите "Информация API" и введите следующий текст:

    Модули, подключаемые к этой точке расширения, должны реализовывать интерфейс <samp>com.example.xyz.IParser</samp>.

    Нажмите Применить.
  4. Выберите "Поставляемая реализация" и введите следующий текст:

    Модуль XYZ содержит стандартную реализацию анализатора.

    Нажмите Применить.
Примечание: При создании примеров требуется учитывать некоторые особенности PDE. Обычно PDE обрабатывает текст как код HTML и не обращает внимания на переводы строки и серии пробелов. Для простого текста так и должно быть, но это очень мешает при обработке примеров, где желательно сохранение макета с отступами по горизонтали и по вертикали для правильного отображения примера. В PDE предусмотрено решение для такой ситуации: все форматирование текста между тегами HTML <pre> и </pre> сохраняется без изменений. Поэтому в документации возможно сохранить правильное оформление примеров, подобных приведенным выше.

Обратите внимание, что при создании документации все больше и больше элементов в редакторе панели Схема помечаются значком "ручки". Это указывает на то, что элемент содержит связанный с ним текст, что служит подсказкой для быстрого поиска пустых мест в документации.

Панель редактора схемы точки расширения

Завершив работу над документацией, займемся справочниками. Это возможно двумя способами. В любой момент можно просмотреть справочный документ, выбрав в всплывающем меню пункт Предварительный просмотр справочника. Можно также указать в параметрах PDE (на вкладке Схема, Параметры > Разработка модулей > Компиляторы), чтобы справочники создавались автоматически при любом изменении схемы. Независимо от способа создания, конечный документ для этого примера будет выглядеть примерно так.