Я был в нескольких командах, где мы старательно разрабатывали UML-диаграммы в начале проекта. По мере развития проекта и приближающихся сроков графики UML оставались где-то позади, а не будут обновляться в течение нескольких месяцев. Когда новый разработчик присоединился к команде, мы продемонстрировали старые UML-диаграммы и продолжали говорить: «О, у нас никогда не было времени на их обновление, пожалуйста, посмотрите исходный код, чтобы получить представление. И не стесняйтесь спрашивать, есть ли у вас никаких сомнений « . Я уверен, что вы все прошли через один и тот же сценарий.
Однако нам больше не нужно составлять истории, поскольку в этой статье показано, как легко и просто включить диаграммы UML в ваш Javadoc, а также обновлять их при каждом изменении репозитория исходного кода. Мы можем сделать это менее чем за несколько минут и за несколько простых шагов.
Начало работы с UmlGraph занимает пять шагов:
- Загрузите исходный код для UMlGraph.
- Скачайте и установите Graphviz.
- Внесите изменения в файл сборки Ant.
- Запустите цель Ant.
- Добавьте эту цель к вашей работе CI.
Шаг 1: Загрузите исходный код для UMLGraph из здесь. Распакуйте содержимое. Чтобы скомпилировать Java-доклет из исходного кода, запустите ant в файле build.xml. Скопируйте файл UmlGraph.jar в свою библиотеку проектов. Если существует несоответствие версий между различными версиями JDK, которые вы используете, вы получите исключение, подобное этому:
java.lang.UnsupportedClassVersionError: Неверный номер версии в файле .class
Убедитесь, что вы перекомпилировали исходный код UMLGraph и скопировали библиотеку в свой проект.
Шаг 2: Загрузите и установите Graphviz из здесь . Точечный файл должен быть постобработан в Graphviz для создания фактической диаграммы UML. Запуск доклета UmlGraph создаст спецификацию диаграммы Graphviz, которая может быть автоматически обработана для создания чертежей png. Вы также можете создавать другие форматы, используя Graphviz. Если Graphviz не установлен, вы получите исключение, как показано ниже:
BUILD FAILED
/Users/meerasubbarao/Development/webservices-samples/build.xml:107: Ошибка
выполнения: java.io.IOException: точка: не найдена
Общее время: 269 миллисекунд
Шаг 3. Изменения в вашем файле build.xml.
Предполагая, что у вас уже есть рабочий проект с файлом сборки Ant. Добавьте следующую цель в файл build.xml, как показано ниже:
<target name="javadocs" depends="build" description="generates javadoc and also UML Diagram"><mkdir dir="${reports.dir}/javadoc"/> <javadoc sourcepath="${src.dir}" packagenames="com.stelligent.*" destdir="${reports.dir}/javadoc" classpathref="java.classpath" private="true"> <doclet name="org.umlgraph.doclet.UmlGraphDoc" path="lib/UMLGraph.jar"> <param name="-attributes" /> <param name="-operations" /> <param name="-qualify" /> <param name="-types" /> <param name="-visibility" /> </doclet> </javadoc> <apply executable="dot" dest="${reports.dir}" parallel="false"> <arg value="-Tpng"/> <arg value="-o"/> <targetfile/> <srcfile/> <fileset dir="${reports.dir}" includes="*.dot"/> <mapper type="glob" from="*.dot" to="*.png"/> </apply></target>
Ряд опций управляет работой генератора диаграмм классов UMLGraph. Они могут быть указаны как параметры в вашем файле сборки, как показано выше.
Подробности о нескольких вариантах:
-output
Specify the output file (default graph.dot).
-d
Specify the output directory (defaults to the current directory).
-qualify
Produce fully-qualified class names.
-horizontal
Layout the graph in the horizontal direction.
-attributes
Show class attributes (Java fields)
-operations
Show class operations (Java methods)
-constructors
Show a class's constructors
-visibility
Adorn class elements according to their visibility (private, public, protected, package)
-types
Add type information to attributes and operations
-enumerations
Show enumarations as separate stereotyped primitive types.
-enumconstants
When showing enumerations, also show the values they can take.
-all
Same as -attributes -operations -visibility -types -enumerations -enumconstants
Посмотрите здесь для большего количества вариантов.
Шаг 4. Запустите цель ant:
откройте командное окно и запустите ant target: ant javadocs, и вы должны увидеть выходные данные как таковые в окне консоли:
meera-subbaraos-macbook-9:webservices-samples meerasubbarao$ ant javadocsBuildfile: build.xmlinit:cleanGenerated:build: [javac] Compiling 22 source files to /Users/meerasubbarao/Development/ci-jobs/jobs/PetStore_Nightly/workspace/webservices-samples/classes [javac] Note: Some input files use unchecked or unsafe operations. [javac] Note: Recompile with -Xlint:unchecked for details.javadocs: [javadoc] Generating Javadoc [javadoc] Javadoc execution [javadoc] Loading source files for package com.stelligent.biz.ws... [javadoc] Loading source files for package com.stelligent.ent.jpa... [javadoc] Constructing Javadoc information... [javadoc] UmlGraphDoc version 5.0, running the standard doclet [javadoc] Standard Doclet version 1.5.0_13 [javadoc] Building tree for all the packages and classes... [javadoc] Building index for all the packages and classes... [javadoc] Building index for all classes... [javadoc] Generating /Users/meerasubbarao/Development/ci-jobs/jobs/PetStore_Nightly/workspace/webservices-samples/reports/javadoc/stylesheet.css... [javadoc] UmlGraphDoc version 5.0, altering javadocs [javadoc] Building Package view for package com.stelligent.biz.ws [javadoc] Building Package view for package com.stelligent.ent.jpa [javadoc] Building Context view for class com.stelligent.biz.ws.SupplierManagerBean [javadoc] Building Context view for class com.stelligent.biz.ws.SupplierManager [javadoc] Building Context view for class com.stelligent.biz.ws.SignonManagerBean [javadoc] Building Context view for class com.stelligent.biz.ws.SignonManager.....BUILD SUCCESSFULTotal time: 8 secondsmeera-subbaraos-macbook-9:webservices-samples meerasubbarao$
Сгенерированный javadoc довольно аккуратен с UML-диаграммами сверху:
Шаг 5: Добавьте эту цель к вашей работе CI.
Если у вас уже есть CI-сервер, такой как Hudson , который работает и выполняет коммитные сборки и ночные сборки, добавление этой новой цели — одношаговый процесс. В моем случае у меня уже запущена ночная работа, я добавил эту цель муравья в свою цель по умолчанию, как показано ниже:
<target name="all" depends="cleanAndDeployForCoverage, javadocs" />
Затем принудительно создайте сборку для задания Hudson, опубликуйте Javadocs, и вы сможете увидеть результаты на панели управления Hudson.
Javadoc со встроенными UML-диаграммами, отображаемыми на панели инструментов Hudson:
Теперь, когда в нашем файле сборки интегрирована UML-диаграмма, а также наша работа CI, мы можем гарантировать, что наша кодовая база и UML-диаграммы всегда синхронизированы. Мы увидели, как включить эти цели-муравьи в наши коммитные сборки или ночные сборки наших заданий CI, а также опубликовали эти артефакты как часть нашего процесса после сборки.
Ресурсы: