// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= Поддержка обработчиков аннотаций в IDE NetBeans. Часть I. Использование проекта Lombok
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: Поддержка обработчиков аннотаций в IDE NetBeans. Часть I. Использование проекта Lombok - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Поддержка обработчиков аннотаций в IDE NetBeans. Часть I. Использование проекта Lombok

image::images/netbeans-stamp-80-74-73.png[title="Содержимое этой страницы применимо к IDE NetBeans 7.2, 7.3, 7.4 и 8.0"]


* *Использование проекта Lombok для пользовательских аннотаций*

Для демонстрации принципов работы нестандартных аннотаций в IDE NetBeans используется проект Lombok, обеспечивающий удобный способ автоматического создания нескольких элементов кода Java, таких как методы получения, методы установки, конструкторы и другие. Дополнительные сведения о функциях проекта приведены на link:http://projectlombok.org/[+странице проекта Lombok+]. Следует, однако, помнить, что проект Lombok включает в себя ряд функций, которые могут работать не во всех средах разработки.

*Для работы с этим учебным курсом требуются программное обеспечение и ресурсы, перечисленные ниже.*

|===
|Программное обеспечение или материал |Требуемая версия 

|link:https://netbeans.org/downloads/index.html[+IDE NetBeans+] |7.2, 7.3, 7.4, 8.0 

|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+Комплект для разработчика на языке Java (JDK)+] |версия 7 или 8 

|link:http://code.google.com/p/projectlombok/downloads/list[+lombok.jar+] |версия 1.12.4 и более поздние 
|===


== Создание проекта Java

В этом упражнении необходимо создать простой проект Java и класс с именем  ``MyBooks.java``  для демонстрации аннотаций в действии.

1. Выберите *Файл > Новый проект* в главном меню, чтобы открыть мастер создания проектов.
2. В списке 'Тип проекта' в категории 'Java' выберите 'Приложение Java'. Нажмите 'Далее'.
3. Введите на странице "Имя и местоположение" мастера текст * ``TestAnn`` * в качестве имени проекта.
4. Введите * ``testann.TestBooks`` * в поле "Создать главный класс", чтобы заменить имя класса по умолчанию. Нажмите кнопку "Завершить".
image::images/newproj.png[title="Создание нового проекта Java в IDE NetBeans"]

После нажатия кнопки "Готово" среда IDE создаст проект приложения Java и откроет класс ``TestBooks.java``  в редакторе. Как вы можете видеть, теперь новый проект отображается в окне "Проекты", а класс  ``TestBooks.java``  находится в пакете  ``testann``  в узле "Исходные файлы".

5. Правой кнопкой мыши щелкните узел с пакетом  ``testann``  в окне "Проекты", затем выберите "Создать" > "Класс Java".
6. Введите * ``MyBooks`` * в поле "Имя класса" и подтвердите создание класса в пакете  ``testann`` . Нажмите кнопку "Завершить".

После нажатия кнопки "Готово" среда IDE откроет новый класс в редакторе.

7. В редакторе исходного кода добавьте три следующих поля в  ``MyBooks.java`` .

[source,java]
----

package testann;

public class MyBooks {   
    *private int year; //fields
    private String title;
    private String author;*

}
----
8. Поместите курсор в объявление класса и нажмите сочетание клавиш CTRL+ПРОБЕЛ для вызова функции автозавершения кода редактора.
9. Выберите  ``MyBooks (int year, String title, String author) - generate``  в списке автозавершения кода, чтобы создать конструктор для  ``MyBooks.java`` .
image::images/generate-constructor.png[title="Автозавершение кода для создания конструктора"]
10. Сохраните изменения.


== Активация пользовательских аннотаций (lombok.jar) для проекта

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

1. Загрузите файл link:http://code.google.com/p/projectlombok/downloads/list[+lombok.jar+] и сохраните его в системе.
2. Щелкните правой кнопкой мыши узел проекта  ``TestAnn``  и выберите команду "Свойства".
3. Выберите категорию "Библиотеки" в диалоговом окне "Свойства проекта".
4. Нажмите кнопку "Добавить JAR/папку" во вкладке "Компиляция" и перейдите к загруженному файлу  ``lombok.jar`` .
image::images/properties1.png[title="Категория 'Библиотеки' в окне 'Свойства'"]

Ресурсы, добавленные на вкладке "Компиляция", соответствуют параметру  ``-classpath``  link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html#options[+компилятора Java+]. Поскольку файл  ``lombok.jar`` является отдельным файлом JAR, содержащим определения аннотаций и процессоры аннотаций, его необходимо добавить в путь к классам проекта, соответствующий вкладке "Компиляция".

5. Выберите в окне "Свойства проекта" категорию "Компиляция".
6. Убедитесь, что флажок "Включить обработку аннотаций" установлен (параметр активирован по умолчанию). Также установите флажок "Включить обработку аннотаций в редакторе". 
image::images/properties2.png[title="Выберите в окне &quot;Свойства проекта&quot; категорию &quot;Компиляция&quot;."]

Параметр "Включить обработку аннотаций" активирует обработку аннотаций при построении и компиляции проекта. Если флажок не установлен, параметр  ``-proc:none``  передается в компилятор Java, и компиляция выполняется без обработки аннотаций. Таким образом, при необходимости обработки аннотаций необходимо установить флажок "Включить обработку аннотаций".

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

7. В окне "Свойства проекта" нажмите кнопку "ОК" и вернитесь в файл  ``MyBooks.java`` .

Развернув узел "Библиотеки" в окне "Проекты", вы увидите, что теперь файл  ``lombok.jar``  находится в списке библиотек проекта.

image::images/projects-window.png[title="узел 'Библиотеки' в окне 'Проекты'"]


== Создание приложения при помощи пользовательских аннотаций Lombok

1. Введите в файле  ``MyBooks.java``  текст  ``@Data``  перед объявлением класса  ``MyBooks`` .  ``@Data``  представляет собой аннотацию, создающую шаблонный код для классов Java: методы получения для всех полей, методы установки для всех неполных полей и соответствующие реализации  ``toString`` ,  ``equals``  и  ``hashCode`` , включающие в себя поля класса.

Дополнительные сведения об аннотациях, поддерживаемых в проекте Lombok, приведены в разделе link:http://projectlombok.org/features/index.html[+Обзор функций+] Lombok.

2. Щелкните всплывающую подсказку в левом поле редактора и добавьте импорт для  ``lombok.Data`` .
image::images/import-lombok.png[title="Подсказка в редакаторе для импорта lombok"]

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


[source,java]
----

package testann;

import lombok.Data;


@Data
public class MyBooks {

    private int year; //fields
    private String title;
    private String author;

    public MyBooks(int year, String title, String author) {
        this.year = year;
        this.title = title;
        this.author = author;
    }
}
----

Обратите внимание, что необходимые артефакты кода, например методы получения, методы установки, toString и другие созданы и отображаются в окне навигатора. Аннотация  ``@Data``  создала весь шаблонный код, необходимый для типичного класса.

image::images/nav.png[title="Окно 'Навигатор', в котором отображаются участники проекта"]

Можно также вызвать окно автозавершения кода (CTRL+ПРОБЕЛ) и проверить доступность созданных артефактов для выбора. Теперь необходимо убедиться, что проект выполняет компиляцию, а созданные артефакты можно вызвать из других компонентов программы.

3. Откройте файл  ``TestBooks.java``  с методом _main_ и добавьте следующий код (выделен полужирным шрифтом), чтобы создать новый объект класса  ``MyBooks`` .

[source,java]
----

package testann;

public class TestBooks {

    public static void main(String[] args) {
        *MyBooks books = new MyBooks(2009, "My Beautiful Dream", "John Smith");*
    }
}
----
4. Добавьте следующий код, который выводит на экран значения переменной  ``books`` .

Для возврата значений следует вызвать методы получения, автоматически созданные в файле  ``lombok.jar`` . Обратите внимание, что при вводе автоматически созданные артефакты доступны в окне автозавершения кода.


[source,java]
----

package testann;

public class TestBooks {

    public static void main(String[] args) {
        MyBooks books = new MyBooks(2009, "My Beautiful Dream", "John Smith");
        *System.out.println("Year: " + books.getYear() + ", Title: " + books.getTitle() +  ", Author: " + books.getAuthor());*
    }
}
----
5. Сохраните изменения.
6. Щелкните правой кнопкой мыши узел проекта в окне "Проекты" и выберите команду "Выполнить" (F6).

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

image::images/output.png[title="Окно вывода после запуска приложения"]

Таким образом, артефакты, созданные при помощи обработчика аннотаций Lombok, доступны из других компонентов программы.


== Что дальше?

* Документация Java SE - link:http://download.oracle.com/javase/6/docs/technotes/guides/language/annotations.html[+Аннотации+]
* Учебный курс Java SE - link:http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html[+Аннотации+]
link:/about/contact_form.html?to=3&subject=Feedback:%20Using%20the%20Annotation%20Processors%20Support%20in%20NetBeans%20IDE[+Отправить отзыв по этому учебному курсу+]