Дополнительное задание #4

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

Надо начать работу в каталоге .../lab4tmp. ПОКА НЕ ИСПОЛЬЗУЙТЕ КАТАЛОГ lab4. (Причина этого выяснится позднее; вы должны будете сделать каталог lab4 на одном из следующих шагов.) Просто скопируйте в этот временный каталог свои старые файлы, потому что они понадобятся вам снова.

Автоматизация процесса проектирования

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

Мы будем использовать Ant. Он используется во многих проектах Java, и имеет огромный набор средств и возможностей. Более того, Ant разработан для запуска на разных платформах и не требует реконфигурации; например, он может преобразовывать символы "/" и "\" в зависимости от операционной системы в которой он запущен. Ant можно загрузить и установить на своем компьютере.

Структура проекта

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

src

Здесь располагается исходный код. Код для тестов не помещается в этот каталог!

test

Здесь располагается тестирующий код. Аналогично правилу для каталога src, здесь не должно быть файлов исходного кода проекта; только код тестов.

lib

Здесь помещаются внешние библиотеки (JAR-файлы) которые нужны для запуска программы, или запуска тестов. (Например, сюда следует поместить JAR-файл TestNG.)

res

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

doc

Здесь вы должны поместить документацию проекта, включая проектную документацию, руководства пользователя, сведения о релизах, списки багов (если вы не пользуетесь сторонней программой баг-трекером), и так далее. (Сейчас у вас скорее всего нет файлов, которые вы можете поместить в каталог doc.)

build

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

В каталоге buildбудут подкаталоги:

• classes - куда помещаются созданные .class файлы
• javadoc - куда записывается документация API

Реструктурируйте ваш код так чтобы он распределился по указанным каталогам. Пока достаточно создать каталоги src, test, и lib, и переписать в них файлы вашего проекта. Если у вас уже есть файлы с документацией (не-Javadoc), их можно поместить в каталог doc. Аналогично, если у вас есть файлы изображений или другие ресурсы, можете записать их в каталог res.

Не следует записывать .class класс файлы в каталог src или test, и записывать куда либо документацию Javadoc. Все это будет создано компилирующим скриптом и появится внутри каталога build во время компиляции.

Файл build.xml

В этом задании можно начать с файла build.xml. (Я обычно сохраняю файл build.xml и использую его как шаблон, для каждого нового проекта.) Загрузите этот файл example-build.xml в свой каталог четвертого задания lab4, и переименуйте его в build.xml.

Просмотрите содержимое этого файла, и изучите правила по которым он составлен. Самое важное обстоятельство, это то что все важные для нас каталоги заданы в виде свойств Ant в самом начале файла, и подкаталоги задаются через свойства каталогов. Например, есть свойство buildDir, и после объявлено свойство buildClassesDir -подкаталог в определении которого подставлено свойство buildDir.

Для того чтобы можно было откомпилировать ваш проект сделайте следующее:

1. Измените имя и описание проекта в файле build.xml. Имя проекта должно быть просто "boggle". Описание должно отражать общую идею проекта и то как его компилировать.

   Результат своей работы можно увидеть выполнив команду "ant -projecthelp" в командной строке.

2. Добавьте цель clean к своему Ant файлу, которая удаляет каталог build и все его содержимое. Добавьте к цели понятное описание. (Подсказка: см. задачу Ant delete. Эта цель должна быть очень проста.)

   Сделайте архивную копию вашей работы прежде чем компилировать цель!

3. Добавьте цель javadoc к Ant файлу, которая использует задачу javadoc Ant для генерации документации API в каталоге заданном свойством javaDocDir. Снова сделайте понятное описание цели. Задайте все каталоги с помощью свойств Ant; не вписывайте каталоги прямо в задачу, так как они почти наверняка потом изменятся.

   (Вы можете добавить или исключить свои тестовые классы в Javadocs. Я обычно не включаю тестовый код в Javadocs, потому, что он имеет тенденцию захламлять этот ресурс предназначенный для помощи разработчикам.)

   Вот еще несколько деталей для реализации вашей цели javadoc:

   • Цель должна иметь зависимость от цели -init.
   • Я обычно устанавливаю атрибуты author, version, и private в "true", потому что это полезная для вывода информация.
   • Целевой каталог (атрибут destdir attribute) должен иметь значение свойства javaDocDir Ant.
   • Чтобы задать файлы исходного кода, можно использовать вложенный элемент <fileset>, примерно так:

         <fileset dir="${srcDir}" />

После того, как все эти задачи выполнены, проверьте как компилируется ваша программа и генерируется для нее документация API. Для этого запустите различные задачи Ant. Например:

    ant clean
    ant compile
    ant clean compile javadoc

Использование TestNG совместно с Ant

Так как TestNG это новый инструмент, Ant не имеет встроенных задач для запуска тестов TestNG! Но это не страшно, так как Ant имеет способ добавления новых типов задач к build-файлу проекта. Для этой цели используется тэг <taskdef>.

Добавьте эти строки к файлу build.xml, после путей к каталогам и перед "Целями(Build Targets)":

    <taskdef resource="testngtasks"
             classpath="path/to/testng.jar" />

Как обычно, используйте свойство Ant чтобы указать путь к JAR-файлу TestNG.

Как только вы это сделали, задачу <testng> можно использовать в вашем проекте. Документацию по этому вопросу можно найти на сайте TestNG. Включите свои модульные тесты в процедуру создания проекта сделав следующее:

1. Добавьте новую цель с именем compile-tests. Начать можно с копирования цели compile. Однако, обязательно внесите в копию следующие изменения:

   • Цель compile-tests имеет зависимость от цели compile, так как (это очевидно) тесты используют классы проекта.
   • Файлы исходного кода тестов располагаются в testSrcDir, а не в srcDir.
   • class-файлы тестов должны помещаться в testBuildDir, а не в buildClassesDir.
   • Путь к файлам классов должен быть test.path, а не libs.path. Так же не забудьте изменить свойство test.path так чтобы оно показывало на JAR-файл TestNG, который должен располагаться в каталоге libDir.
   • Дайте новой цели подходящее описание.

2. Добавьте новую цель test в свой Ant файл. Она должна запускать все модульные тесты с помощью задачи testng. Как обычно, напишите понятное описание цели. Вот еще несколько деталей которые помогут вам завершить создание цели:

   • Эта цель имеет зависимость от задачи compile-tests.
   • Вашей ели нужна только одна задача, testng.
   • Задайте атрибут suitename, потому что значение по умолчанию "Ant suite" слишком громкое. Укажите что то вроде "boggle-tests".
   • Результаты тестов должны попасть в каталог testResultsDir . (См. свойство outputdir.)

   • classpath для задачи testng указывается одним из трех способов; можно указать атрибут classpath, или атрибут classpathref , или добавить вложенный элемент <classpath>. Одно тонкое место здесь, это то что test-path не содержит путь к откомпилированным тестовым классам. Поэтому нужно указать что то вроде этого:

         <classpath>
           <path refid="test.path" />
           <pathelement path="${testBuildDir}" />
         </classpath>

     Другими словами, мы включаем путь test.path, и затем еще добавляем содержимое testBuildDir.

   • Наконец надо задать список запускаемых тестовых классов. Для этого можно использовать вложенный элемент <classfileset>.

Когда вы закончили с целями compile-tests и test, запустите их и посмотрите как они работают. Если все в порядке, можете открыть каталог build/results и посмотреть простой HTML отчет ваших модульных тестов.

Полная автоматизация компиляции проекта

После того как все ваши цели заработали, раскомментируйте цель full, и измените цель по умолчанию вашего проекта на full. Теперь если вы запустите ant без аргументов, он запустит цель full все ее зависимости.

Контроль версий с помощью Subversion

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

Поместите ваш проект в репозиторий Subversion кафедры. Есть несколько способов сделать это. Возможно проще всего использовать клент Subversion с графическим интерфейсам. Правила работы с одним из таких клиентов для Windows описаны  в этом документе. В раздеде Subversion есть ссылки на графические клиенты для Linux и Mac OS. Если вы предпочитаете работать в командной строке Linux, изучите приведенные ниже инструкции. 

В ответе на это задание не нужно загружать в Moodle какие либо файлы. Следует только указать путь к вашему проекту в репозитории Subvresion, например:

 /ivans/java-course/boggle

Клиент Subversion в командной строке Linix

Есть несколько способов подключиться к серверу Subversion из командной строки Linux. Здесь описан способ подключения по протоколу HTTPS. На практике удобнее использовать svn+ssh, но наш сервер не поддерживает этот протокол. Следует отметить6 что если соединение огранизуется по HTTP, то надо использовать защищенную версию этого протокола, чтобы пароли и имена пользователей не передавались открытым текстом. Так сделано и в нашем случае.

1.  Напервом этапе обычно создается новый репозиторий Subversion. Это делается командой svnadmin create на сервере, например:

       svnadmin create ~/home/joe/advjava/svnrepo

    Но, в данном случае вам надо поместить файлы в отдельный каталог уже созданного репозитория. Поэтому этот шаг следует пропустить и перейти к импорту проекта.
2. Импортируйте все файлы исходного кода в репозиторий Subversion. Ваши файлы уже хорошо структурированы, но нужно удалить все результаты компиляции ( с помощью ant clean), а также удалить временные файлы редактора, такие как *~, и пр.

3. Когда ваши файлы подготовлены для импорта, выполните его командой svn import.  (Можно также импортировать удаленный репозиторий командой svn+ssh:// URL, но с этим если хотите разберитесь сами .) Выполните эту команду в каталоге lab4tmp:

       svn import https://<имя хоста>/svn/<имя пользователя>/advjava/boggle --trust-server-cert --non-interactive -m "<сообщение>" --username <имя пользователя> --password <пароль>

   (Конечно, замените <имя пользователяe> на ваше имя пользователя под которым вы зарегистрированы на этом сайте, <имя хоста> на имя сервера Subversion, <пароль> на ваш пароль от сервера Subversion /как его получить см. сдесь./ <сообщение> можно оставить пустым "" или ввести строку поясняющую ваше действие. Наример "импорт проекта". Это сообщение будет сохранено сервером Subversion. Если убрать ключ -m из командной строки то перед исполненим команды появится окно редактора в котором нужно будет вести эту поясняющую строку)

   Эта команда рекурсивно импортирует все файлы из вашего локального каталога, в репозиторий. "boggle" в конце URL репозитория означает, что ваш проект будет помещен в каталог "boggle" репозитория.

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

   Если Subversion сообщит о том что не может найти редактор, можете вылечить это например такой командой: export EDITOR=vi перед тем, как выполнять команды Subversion. (Замените vi именем своего любимого текстового редактора.)

4. Импорт файлов из каталоге не делает этот каталог автоматически рабочей копией репозитория! Поэтому после импорта, нужно загрузить (эта операция называется checkout) файлы из репозитория в локальный каталог. Так можно к тому же проверить что импорт прошел успешно. Создайте новый каталог ~/cs11/advjava/lab4, и сделайте checkout в этот каталог. Примерно так:

   svn checkout https://<имя хоста>/svn/<имя пользователя>/advjava/boggle --trust-server-cert --non-interactive --username <имя пользователя> --password <пароль>

   Эта команда создаст локальный каталог boggle, содержащий файлы которые вы только что импортировали. Проверьте что там есть все файлы которые вы рассчитывали найти! Когда вы убедитесь что все в порядке, тогда можете стереть временный каталог lab4tmp.

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

Команду svn commit можно вызывать без параметров не указывая URL репозитория потому, что Subversion создает небольшие файлы .svn в каталоге рабочей копии, которые содержат всю необходимую информацию включая имя репозитория. (Их можно увидеть командой "ls -a" в каталоге рабочей копии.)

Вы можете использовать команды svn help и svnadmin help чтобы получить дополнительную информацию о командах Subversion.

Вот несколько интересных задач, которые вы можете попробовать решить, если хотите лучше изучить Ant и Subversion.

• Начиная с Java 1.4, инструмент Javadoc позволяет вам добавлять собственные тэги Javadoc к вашей документации. Я часто использую это свойство для того чтобы улучшить документацию своих проектов:

      /**
       * Мой прекрасный класс генератор виджетов.
       *
       * @todo Убедится что все виджеты работают!
       **/
      public class WidgetGenerator {
          ...
      }

  В этом случае, тэг Javadoc @todo не относится к набору стандартных тэгов Javadoc (хотя он есть в списке предлагаемых новых тегов). Однако его можно добавить к генерируемым тегам правильно настроив инструмент Javadoc. Так как вы используете Ant, эта настройка делается просто. Задача Ant javadoc поддерживает вложенные элементы <tag>, например такие:

      <javadoc ...>
          ...
  
          <tag name="todo" description="To Do:" />
      </javadoc>

  Добавьте следующие тэги Javadoc:
  • @todo bla bla bla - описывает что нужно доделать в будущем
  • @design bla bla bla - описывает проектные решения и намерения
  • @review (user) bla bla bla - когда вы просматриваете чей то код, вы можете оставить комментарий описывающий какую то особенность или проблему в коде

• Посмотрите свойство svn:ignore в документации Subversion. Это свойство можно установить для любого каталога; оно позволяет указать список файлов и подкаталогов которые Subversion игнорирует выполняя свои операции. Вернитесь в корневой каталог проекта Boggle и добавьте каталог build к свойству svn:ignore. (Подсказка: см. svn propedit)

  Можете проверить свою работу командой svn status в корневом каталоге после завершения компиляции; если каталог build игнорируется все сделано правильно.

Copyright (C) 2015, California Institute of Technology. All rights reserved.