Разработчики наконец поняли, что создание систем по модульному принципу облегчает обновление одной части системы без влияния на остальные части. Модульность также облегчает расширение оригинальной системы для реализации новых идей. Это и было мотивацией для создания среды Eclipse в виде набора подключаемых модулей, что позволяет разработчикам заменять и улучшать уже существующие модули.

Справочная система в Eclipse, как и остальная среда, построена по принципу подключаемого модуля. В этой статье обсуждаются преимущества этой полезной архитектуры для формирования содержимого справочной системы. Предполагается, что вы имеете практические знания по темам Java™, Eclipse и Web. Каких-либо знаний об организации справочной системы в Eclipse или о работе подключаемых модулей не требуется. Цель статьи – показать, как и почему можно организовать справочную систему для среды Eclipse на центральном сервере (либо в интранете, либо в интернете) и обращаться к ней из среды.

Зачем нужна централизация?

Справочная система в Eclipse не является монолитной сущностью. Это набор подключаемых модулей, соединенных вместе для представления в виде единого модуля. Но даже это на самом деле не дает ответ на вопрос: "Почему я захочу централизовать справочную систему в Eclipse? Если я загрузил Java-версию Eclipse, то разрабатываю приложения на Java и имею все необходимые мне справочные данные локально." Это также верно для всей вашей команды разработчиков. Каждый из вас имеет свою собственную локальную справочную систему, которая работает хорошо до тех пор, пока однажды на горизонте не появятся дополнительные подключаемые модули.

Нашествие подключаемых модулей

В реальном проекте наступит день, когда вы поймете, что вы и другие члены вашей команды разработчиков нуждаетесь в функциях какого-либо подключаемого модуля или двух (или, поскольку они имеются в изобилии и недороги, пару дюжин). Для любой нетривиальной командной разработки вы должны быть уверены, что среда у каждого разработчика является одинаковой, от процесса компоновки до JAR-файлов сторонних разработчиков, которые вы используете. Это просто хорошая практика разработки проекта - уверенность в том, что каждый в команде работает над созданием одного и того же проекта. Фактически, большое количество инструментальных средств сторонних разработчиков созданы для управления этим процессом: Ant, программа Java Make, CruiseControl для возможности последовательной интеграции и масса других. Опытные Java-разработчики осознают необходимость репродуцирования среды разработки и процесса для всей команды. Почему справочная система должна отличаться?

При установке подключаемых модулей в Eclipse наиболее продвинутые из них устанавливают свою собственную справочную систему и, из-за способа организации этой системы в Eclipse, они выглядят достаточно интегрированными в существующую инфраструктуру справочной системы. Вот где наличие внешней доступной информационной среды окупается. Ведь другие аспекты процесса разработки вы хотите сохранять в непротиворечивом состоянии, так почему бы этого не сделать для справочной системы? Cправочная cистема охватывает существующую систему в Eclipse, и к ней также присоединяются справочные системы отдельных подключаемых модулей.

Для наилучшего использования справочной системы вы должны добавить в нее свое содержимое с добавлением к стандартным элементам справки своих элементов, относящихся к проекту и команде разработки. Вы можете загрузить подключаемый модуль, облегчающий вашу работу, но необходимо убедиться, что каждый член команды использует его одинаковым способом и имеет доступ к тем же самым его элементам. Если вы разместите всю эту информацию в одном месте, вы уменьшите потенциальную вероятность ее десинхронизации. Это также считается передовым опытом, указанным в книге "Прагматический программист" Дэйва Томаса (Dave Thomas) и Энди Ханта (Andy Hunt) (смотрите раздел "Ресурсы"). Они объяснили принцип Don't Repeat Yourself (DRY) (не повторяйся): Если вы имеете одну и ту же информацию в более чем одном месте, вы потеряете синхронизацию, и не сможете доверять ни одному конкретному ее экземпляру. Если вы "не повторяетесь", то вы знаете, что единственная копия - это каноническая копия. Это относится и к справочной системе.

В начало

Организация справочной системы в Eclipse

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

Самым простым способом увидеть внутреннюю структуру справочной системы является создание подключаемого модуля, расширяющего эту систему. Eclipse поставляется с системой Plug-in Development Environment (PDE), поэтому создание нового подключаемого модуля не является проблемой. Прежде всего создайте новый проект подключаемого модуля одним из нескольких способов: выберите File>New Project, File>New Plug-in Project..., либо используйте галерею проектов, применяя комбинацию Control-N. Выбрав какой-нибудь из двух вариантов создания типичного проекта, вы увидите диалоговое окно New Project, показанное на рисунке 1.

На следующем шаге мастера у вас есть возможность указать детальную информацию о вашем проекте, такую как имя и структуру каталогов. Это диалоговое окно изображено на рисунке 2.

В данном случае вы создаете только точку расширения подключаемого модуля справочной системы. Однако PDE поставляется с большим количеством предварительно созданных точек расширения, включая одну для расширения справочной системы. Для просмотра списка точек расширения отметьте флажок Create a Java Project в Project Settings, (см. рисунок 2), иначе примерные точки расширения не появятся в следующем диалоговом окне мастера. В данном случае вы в конечном итоге создаете Java-код, поэтому и выбран этот вариант. Если вы хотите создать только справочную систему и не желаете использовать предопределенные точки расширения, оставьте этот флажок отмеченным.

Следующая страница мастера позволяет вам указать мета-информацию о вашем подключаемом модуле. Она показана на рисунке 3.

Для облегчения создания подключаемых модулей PDE поставляется с множеством шаблонов, включающих и модули предопределенного типа. Мы собираемся использовать преимущества этих шаблонов для создания инфраструктуры вокруг модуля справочной системы. На рисунке 4 показана страница мастера, на которой можно выбрать шаблон.

Мастер обычного подключаемого модуля предоставляет много точек расширения, одна из которых является расширением справочной системы, что показано на рисунке 5.

Наконец, на последней странице мастера вы выбираете тип содержимого, которое будет предоставлять наш подключаемый модуль справочной системы, что показано на рисунке 6.

Конечным результатом нашей экскурсии по мастеру PDE явился набор файлов, включая XML, Java-код и структуру компоновки.

Внутри TOC

Последняя страница мастера PDE (показанная на рисунке 6) создает файл TOC.XML, таблицу содержания (TOC) для файлов справки, которые вы включаете в ваш подключаемый модуль. Формат TOC используется для внутренней справочной системы Eclipse и для подключаемых модулей; он постоянен по всей системе. Генерируемый по умолчанию TOC-файл выглядит примерно так, как показано в листинге 1.

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Repository Table of Contents" topic="html/toc.html">
   <topic label="Getting Started">
      <anchor id="gettingstarted"/>
   </topic>
   <topic label="Concepts">
      <anchor id="concepts"/>
   </topic>
   <topic label="Tasks">
      <anchor id="tasks"/>
   </topic>
</toc>

Обратите внимание, что заголовок, созданный на рисунке 6, появляется в верхнем теге <toc>, и это является пунктом для темы в html/toc.html. TOC-запись является верхним уровнем структуры каталогов справочной системы для этого набора. Другими словами, физические HTML-файлы справки будут находиться в указанной здесь структуре каталогов, ниже корневого каталога. Обычно, для уменьшения занимаемого пространства эти HTML-файлы находятся в zip-архиве (традиционно называемом doc.zip). Если вы просмотрите каталоги подключаемых модулей вашей среды Eclipse, то увидите множество файлов doc.zip, каждый из которых содержит информацию, присоединяемую к главной справочной системе Eclipse при любом вызове справки.

Другие записи в TOC-файле указывают на другие TOC-файлы, сгенерированные тогда же, что и первичный TOC. У вас имеются "gettingstarted", "concepts" и "tasks." Каждая из этих вторичных TOC-записей имеет в проекте соответствующий XML-файл таблицы содержания. Также PDE создает в проекте нужную структуру каталогов для HTML-файлов содержания, как это видно из снимков окна package explorer на рисунке 7.

Из-за такой структуры вы можете создать так много файлов справки соответствующей структуры, сколько пожелаете, и поместить их в zip-файлы для объединения в одну цельную справочную систему Eclipse.

В начало

Создание внешнего репозитория

Теперь, когда вы знаете, как структурированы справочные файлы Eclipse, приступим к рассмотрению того, как выделить их на независимый сервер. Eclipse способствует этому, предоставляя инструмент, называемый Infocenter. Как вы, возможно, уже догадались, справочная система Eclipse фактически поддерживается встроенным Web-сервером и механизмом сервлетов. На самом деле в качестве сервера приложения справочной системы используется урезанная версия Apache Tomcat. Одним из подключаемых модулей, поставляемых вместе с Eclipse, является org.eclipse.help.appserver_3.0.0. Он то и инкапсулирует Web-сервер. Infocenter выделяет сервер приложений так, что вы можете управлять им вне среды Eclipse.

Infocenter

Чтобы установить Infocenter на внешнем сервере, установите Eclipse Runtime Binary (который вы можете загрузить с Eclipse в виде zip-файла). Извлеките его в структуру каталогов на вашем сервере (отмечу, что эта процедура абсолютно аналогична установке Eclipse, которую вы делали на сервере). Infocenter поддерживает все функциональные возможности внутренней справочной системы, за исключением infopop (контекстно-чувствительной системы всплывающих подсказок) и Active Help (выполняющей команды из окна справки вместо вас, например создание нового файла). Эти расширенные функции справки нельзя реализовать на внешнем сервере. Infocenter содержится в Runtime Binary в виде набора Java-классов, вызываемых из командной строки.

Для запуска Infocenter на вашем сервере выполните приведенную в листинге 2 команду, в которой [ehome] - это каталог, в который установлен ваш Eclipse (команда разбита на несколько строк для улучшения читабельности; она должна быть введена в одной строке).

java 
-classpath [ehome]\plugins\org.eclipse.help.base_3.0.1\helpbase.jar
org.eclipse.help.standalone.Infocenter 
-eclipsehome [ehome] 
-port 8081
-command start

Эта команда устанавливает classpath для указания JAR-файла Infocenter, указывает каталог установки Eclipse, устанавливает номер порта и запускает команду start. Для остановки сервера выполняется такая же команда с shutdown вместо start. После запуска Infocenter вы можете использовать браузер и перейти по URL, например http://localhost:8081/help/index.jsp.

В своем браузере вы увидите стандартную справочную систему Eclipse, что показано на рисунке 8.

Infocenter без ограничений

Infocenter является автономным сервером, поэтому он не требует дополнительного Web-сервера. Однако в реальной среде вы хотите управлять такими важными вопросами, как доступом, видимостью, и другими аспектами, которые можно контролировать при работе обычного Web-сервера. Вы легко можете настроить ваш Web-сервер на перенаправление команд в Infocenter, основываясь на определенном шаблоне URL.

Например, вы можете установить прокси-модуль в Apache для перенаправления запросов вида http://bigsprawlingcompany.com/eclipsehelprepo в URL для Infocenter, который выглядит как http://internalhelpserver:8081/help, при помощи следующих изменений файла conf/httpd.conf Apache:

LoadModule proxy_module modules/ApacheModuleProxy.dll
ProxyPass /eclipsehelprepo http://internalhelpserver:8081/help 
ProxyPassReverse /eclipsehelprepo http://internalhelpserver:8081/help

В начало

Подключение доступа к вашей справочной системе

Теперь, после выделения справочной системы на внешний сервер, вам необходим способ доступа к ней из Eclipse. Существует несколько способов это сделать. В данной статье мы создадим новый элемент меню верхнего уровня, который ведет к новому удаленному репозиторию. Вы можете изменить существующее поведение справочной системы, перезаписав существующие элементы меню, но это делать не рекомендуется. Обычно является плохой идеей ломать то, что уже существует, особенно в данном случае. Вам не нужно лишать разработчиков возможности пользоваться локальной справочной системой, если, например, ваш удаленный сервер не работает. Лучше всего при разработке подключаемых модулей использовать частичный вариант клятвы Гиппократа: прежде всего - не навреди.

Простейшим способом создания нового элемента меню является использование мастера PDE для построения инфраструктуры за вас. Для создания элемента меню справочного репозитория используется та же последовательность, что и прежде при изменении одной из страниц мастера. На странице выбора шаблона, изображенной на рисунке 5, был добавлен новый элемент Sample Action, как показано на рисунке 9.

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

Эта страница позволяет дать название (и впоследствии создаст) классу Action. Этот класс Action содержит шаблон кода для добавления нового действия в Eclipse, в данном случае связанного с элементом меню. Единственный кодом, который вы должны добавить - код вызова окна просмотра справочной информации, которым может быть стандартное окно просмотра справочной информации Eclipse или браузер. В данном случае мы собираемся использовать браузер пользователя по умолчанию. Использование готового браузера обеспечивает все те же преимущества, что и использование окна просмотра справочной информации, но также позволяет пользователю создавать закладки к коду репозитория вместе с закладками, найденными в Web, которые тоже могут относиться к разработке. Код в методе run() занимает одну строку:

public void run(IAction action) {
     Program.launch("http://localhost:8081/help");

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

В начало

Объединение всего вместе

После создания подключаемого модуля меню вы можете соединиться с вашей выделенной в отдельный сервер справочной системой Infocenter из главного меню Eclipse. На рисунке 11 показано это меню.

После выбора этого меню вызывается справочная система Infocenter в каком-либо браузере, который вы настроили на вашем компьютере. Конечный результат изображен на рисунке 12.

Вуаля! Теперь вы имеете внешний репозиторий справочной информации, в котором вы можете начать компоновать справочную систему для всей вашей команды разработчиков приложений. Как только вы привыкнете к этому ресурсу, вы удивитесь тому, как вы раньше обходились без него.

В начало

Резюме

Теперь, когда вы объединили все рассмотренные в этой статье вопросы воедино, вы в итоге имеете больше, чем простую сумму знаний этих вопросов. Вы можете создать для ваших разработчиков гибко настраиваемую систему справочной информации со справочной информацией всех соответствующих подключаемых модулей и даже с вашим собственным содержимым. Было бы не плохой идеей разместить стандарты кодирования, принятые в компании, в справочной системе, непосредственно возле других справочных материалов.

Если вы создаете справочную систему вне среды разработки, она становится доступной разработчикам из дома или с удаленного клиентского места. Система справочной информации становится бесценным справочным ресурсом. Фактически, выделение справочной системы дает вам возможность считать ее чем-то значительно большим, чем статический набор информации, обрушившийся на вас от поставщиков. Вы можете сделать справочную систему динамической интегральной частью вашей среды разработки.

Ресурсы

Научиться

• Оригинал статьи "Centralizing help in Eclipse".
  
  
• Apache Ant - это основанная на Java программа компоновки. Теоретически она похожа на Make, но без его недостатков.
  
  
• CruiseControl - это среда для непрерывного процесса компоновки.
  
  
• В книге Дэйва Томаса (Dave Thomas) и Энди Ханта (Andy Hunt) "Программист-прагматик: От подмастерье к мастеру" (Addison-Wesley Professional, 1999) объясняется принцип DRY и дюжина других важных концепций.
  
  
• Детальный обзор архитектурного шаблона для построения приложения из компонентов, реализованных в подключаемых модулях Eclipse, приведен в статье "Заметки по архитектуре подключаемого модуля Eclipse".
  
  
• Детальные инструкции по установке Web-приложения Infocenter на сервере можно найти в "Установка Infocenter".
  
  
• Статья IBM developerWorks "Разработка подключаемых модулей Eclipse" посвящена созданию, отладке и установке подключаемых модулей Eclipse
  
  
• Просмотрите ресурс WebSphere Application Developer Infocenter.
  
  
• Посетите зону открытых исходных текстов developerWorks для поиска детальной информации how-to, инструментальных средств и обновлений проекта, помогающих вам разрабатывать приложения с использованием технологий и продуктов с открытым исходным кодом и использовании этих технологий совместно с продуктами IBM.
  
  

Получить продукты и технологии

• Примените в вашем следующем проекте с открытым исходным кодом пробное программное обеспечение IBM, доступное для загрузки или на DVD.
  
  

Обсудить

• Подключайтесь к сообществу developerWorks, участвуя в блогах developerWorks.
  
  

Об авторе

Оценить эту статью

Комментарии

В начало

Содержание

• Зачем нужна централизация?
• Организация справочной системы в Eclipse
• Создание внешнего репозитория
• Подключение доступа к вашей справочной системе
• Объединение всего вместе
• Резюме
• Ресурсы
• Об авторе
• Комментарии