Лекция A1. Утилиты
#######################################################################################



Core-утилиты
===========================================================


Jar
-----------------------------------------------------------


Программный архив Jar
``````````````````````````````````````````````````````````

Программный архив **JAR** содержит ресурсы и class-файлы программы.


Запуск программы:

.. admonition::  Jar

   java -jar имя.jar
Создание архива:


#. Компиляция **javac *.java**
#. Подготовка **Manifest**-файла: **Main-Class: Hello**
#. Упаковка: **jar cvmf Hello.jar Mainfest.txt *.class**


Запуск:


**java -jar Hello.jar**


Альтернативный запуск: **java -cp Hello.jar Hello**

Javadoc
-----------------------------------------------------------


Аннотации
``````````````````````````````````````````````````````````

**Аннотация** — в языке Java специальная форма синтаксических метаданных, которая может быть добавлена в исходный код. Аннотации используются для анализа кода, 

компиляции или выполнения.


Аннотируемы пакеты, классы, методы, переменные и параметры.
Наиболее популярные аннотации:


* **@Override** - проверка замещения метода. Вызывает ошибку компиляции, если метод не найден в родительском классе;
* **@Deprecated** - отметка устаревания метода. Вызывает предупреждение компиляции, если метод используется;


.. code-block:: java

 public class Figure {
     public void draw() {
         ...
     }
 }
 public class Point extends Figure {
     @Override // переопределено
     public void draw() {
         ...
     }
     @Deprecated  // устарело 
     public int getX() {
         ...
     }
 }


Еще примеры аннотаций:



.. code-block:: java

 @Author(
    name = "Vasya Pupkin",
    date = "10.10.2010"
 )
 class MyClass() { }



Аннотации javadoc
``````````````````````````````````````````````````````````



.. code-block:: java

 /**
  * Returns an Image object that can then be painted on the screen.  
  *
  * @param  url  an absolute URL giving the base location of the image
  * @param  name the location of the image, relative to the url argument
  * @return      the image at the specified URL
  * @see         Image
  */
  public Image getImage(URL url, String name) {
         try {
             return getImage(new URL(url, name));
         } catch (MalformedURLException e) {
             return null;
         }
  }



Документирование
``````````````````````````````````````````````````````````

Рассмотрим исходный файл **DemoKey.java**:



.. code-block:: java

 /**
   * <p>Класс "Ключ" - 
   * простая абстракция ключа</p>
   * пока реализовано 3 метода
   */
 class Key
 {
     /**
     * Вставка ключа в замок
     */
     void push() {
         System.out.println("push key");
     }
     /**
     * Поворот ключа
     */
     void turn() {
         System.out.println("turn key");
     }




.. code-block:: java

     /**
     * Извлечение ключа из замка
     */
     void pop() {
         System.out.println("pop key");
     }
   /**
     * Метод открытия двери
     */
     public void open() {
         push();
         turn();
         pop();
         System.out.println("Open!");
     }
 }




.. code-block:: java

 /**
   * <p>Демонстрация работы с ключом</p>
   * Ключ используется для открытия двери
   */
 public class DemoKey
 {
     public static void main(String[] args) {
         Key key=new Key();
         key.open();
     }
 }


Запуск **javadoc**:



.. code-block:: none

 javadoc -charset utf-8 -private -d info DemoKey.java


В этой команде:


* **charset** - кодировка выходного документа (веб-страницы)
* **private** - включать информацию о закрытых классах
* **d** - каталог для размещения документацииы
Результат:



.. image:: _static/A1/javadoc1.png


Автоматизация компиляции
===========================================================


Ant
-----------------------------------------------------------


.. image:: _static/A1/ant.png


**Ant** - наиболее старая утилита автоматизации сборки Java-программ, похожая на **Make**

Файл сборки (**build.xml**) включает в себя главный контейнер **project**, внутри которого расположены различные цели сборки

(**targets**)



.. code-block:: xml

 <project name="..." default="all" >
   <target name="...">
   </target>
   <target name="...">
   </target>
   <target name="...">
   </target>
   <target name="...">
   </target>
 </project>


Примеры целей:


Создание каталогов для исполняемых файлов:



.. code-block:: xml

   <target name="make.dirs" description="Make some dirs">
      <mkdir dir="build"/>
      <mkdir dir="build/classes"/>
   </target>


Компиляция:



.. code-block:: xml

   <target name="compile" description="compile java"  
                          depends="make.dirs">
      <javac destdir="build/classes">
      <src path="src"/>
      </javac>
   </target>



В качестве исходников берутся файлы из подкаталога **src**
Подготовка JAR-файла:



.. code-block:: xml

   <target name="jar" description="make jar file" 
                      depends="compile">
      <jar destfile="build/jar/Hello.jar">
         <fileset dir="build/classes">
             <include name="**/*.class"/>
         </fileset>
 	<manifest>
 	   <attribute name="Main-Class" value="Hello"/>
 	</manifest>
     </jar>
   </target>


Манифест генерируется автоматически с данными, описанными в разделе **manifest**
Очистка проекта:



.. code-block:: xml

  <target name="clean" description="clean up">
      <echo>I'm cleaning up.</echo>
      <delete dir="build"/>
   </target>


С помощью **Ant** можно запускать программы на выполнение:



.. code-block:: xml

   <target name="run">
     <java jar="build/jar/Hello.jar" fork="true"></java>
   </target>


Варианты запуска **Ant**:


* ant compile
* ant jar
* ant run
* ant clean
Могут быть другие варианты, зависящие от разделов **target**

Maven
===========================================================


Введение в Maven
``````````````````````````````````````````````````````````


.. image:: _static/A1/maven-logo.png



* инструмент для сборки и управления проектами (build tool)
* инструмент для управления жизненным циклом проекта проекта 
* инструмент для автоматизации

Ключевые преимущества
``````````````````````````````````````````````````````````


* декларативный язык описания проекта (POM)
* автоматическое управление зависимостями
* огромный, поддерживаемый в актуальном состоянии репозиторий артефактов
* модульная расширяемая за счет плагинов архитектура, огромное количество плагинов

Проверка запуска
``````````````````````````````````````````````````````````


.. code-block:: none

 mvn -version


Результат:



.. image:: _static/A1/mvn.png


Схема работы
``````````````````````````````````````````````````````````


.. image:: _static/A1/maven-scheme.png


Артефакты
``````````````````````````````````````````````````````````

**Артефакт** - это конечная цель построения проекта (class,jar,war,...)


Результатом работы Maven является создание (построение) артефакта, а так же ряд дополнительных действий над ним (тестирование, инсталляция в локальный 

	репозиторий, deployment)


Сам артефакт зависит от других артефактов (наших и внешних, плагинов maven)

POM-файл
``````````````````````````````````````````````````````````

**POM - Project Object Model**, xml файл, обычно называется pom.xml


POM файл содержит описание проекта  и все специфические его настройки.




.. code-block:: xml

 <project xmlns=...> 
   <modelVersion>4.0.0</modelVersion>
   <groupId>org.codehaus.mojo</groupId> 
   <artifactId>my-project</artifactId> 
   <version>1.0</version>
 </project>



Структура каталогов
``````````````````````````````````````````````````````````



.. list-table:: 



   * - home 
     -  корневой каталог. Содержит **pom.xml** 


   * - src/main/java 
     -  исходный java-код 


   * - src/main/resources 
     -  ресурсы, файлы свойств 


   * - src/test/java 
     -  тесты для проекта 


   * - src/test/resources 
     -  ресурсы для тестов 



Жизненный цикл проекта
``````````````````````````````````````````````````````````


#. **clean** - очистка проекта
#. **default** - построение проекта из исходных кодов
#. **site** - построение вторичных артефактов (документация, wiki, ...)


Набор фаз
``````````````````````````````````````````````````````````


* **validate** - проверка корректности данных проекта;
* **compile** - компиляция исходного кода;
* **test** - unit-тестирование;
* **package** - упаковка результата компиляции в JAR или т.п.
* **integration-test** - прогон сборных тестов;
* **verify** - проверка целостности пакета (JAR);
* **install** - помещение пакета в локальное хранилище;
* **deploy** -  помещение пакета в удаленное хранилище.  
Выполнение фазы осуществляется командой:



.. code-block:: none

 mvn [имя фазы]


При выполнении определенной фазы автоматически последовательно выполняются все предыдущие фазы (те фазы от которых зависит выполняемая):



.. code-block:: none

 mvn package
 validate -> compile -> test -> package


Вопросы для самоконтроля
=============================================