// 
//     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.
//

= NetBeans IDE 中的标注处理程序支持 - 第一部分：使用 Project Lombok
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: NetBeans IDE 中的标注处理程序支持 - 第一部分：使用 Project Lombok - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, NetBeans IDE 中的标注处理程序支持 - 第一部分：使用 Project Lombok

image::images/netbeans-stamp-80-74-73.png[title="此页上的内容适用于 NetBeans IDE 7.2、7.3、7.4 和 8.0"]


* *使用支持定制标注的 Project Lombok*

为了演示定制标注如何在 NetBeans IDE 内正常工作，我们将使用 Project Lombok，它提供了自动生成多个 Java 代码元素（如 getter、setter 以及构造函数等）的便捷方式。有关其功能的详细信息，请访问 link:http://projectlombok.org/[+Project Lombok 网站+]。但是，请记住，Project Lombok 包含一些可能无法在所有开发环境中正常工作的功能。

*要学完本教程，您需要具备以下软件和资源。*

|===
|软件或资源 |要求的版本 

|link:https://netbeans.org/downloads/index.html[+NetBeans IDE+] |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+] |v1.12.4 或更新版本 
|===


== 创建新的 Java 项目

在本练习中，将创建一个简单的 Java 项目，以及名为  ``MyBooks.java``  的类，用于在操作中演示标注。

1. 从主菜单中选择 *File > New Project*（文件 > 新建项目）以打开新建项目向导。
2. 在 "Java" 类别中选择 "Java Application"（Java 应用程序）项目类型。单击 "Next"（下一步）。
3. 在向导的 "Name and Location"（名称和位置）页中，键入 * ``TestAnn`` * 作为项目名称。
4. 在 "Create Main Class"（创建主类）字段中键入 * ``testann.TestBooks`` *，以替换默认的类名。单击 "Finish"（完成）。
image::images/newproj.png[title="在 NetBeans IDE 中创建新 Java 项目"]

单击 "Finish"（完成），此时 IDE 将创建 Java 应用程序项目，并在编辑器中打开  ``TestBooks.java``  类。您可以看到，新项目现在显示在 "Projects"（项目）窗口中，并且  ``TestBooks.java``  类位于 "Source Packages"（源包）节点下的  ``testann``  包中。


. 在 "Projects"（项目）窗口中，右键单击  ``testann``  包节点，然后选择 "New"（新建）> "Java Class"（Java 类）。


. 键入 * ``MyBooks`` * 作为类名，并确认将在  ``testann``  包中创建类。单击 "Finish"（完成）。

单击 "Finish"（完成）后，IDE 将在编辑器中打开新类。


. 在源代码编辑器中，将以下三个字段添加到  ``MyBooks.java``  中。

[source,java]
----

package testann;

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

}
----


. 将插入光标放在类声明中，然后按 Ctrl-空格组合键，以调用编辑器的代码完成支持。


. 在代码完成列表中选择  ``MyBooks (int year, String title, String author) - generate`` （MyBooks (int year, String title, String author) - 生成），以生成  ``MyBooks.java``  的构造函数。
image::images/generate-constructor.png[title="用于生成构造函数的代码完成功能"]


. 保存所做的更改。


== 为项目启用定制标注 (lombok.jar)

在本练习中，将修改项目的 "Properties"（属性）窗口，以便将库添加到项目的类路径中，并在编辑器中启用标注处理功能。

1. 下载 link:http://code.google.com/p/projectlombok/downloads/list[+lombok.jar+] 文件并将其保存在系统上。
2. 右键单击  ``TestAnn``  项目节点，然后选择 "Properties"（属性）。
3. 在 "Project Properties"（项目属性）对话框中，选择 "Libraries"（库）类别。
4. 单击 "Compile"（编译）标签中的 "Add JAR/Folder"（添加 JAR/文件夹），找到您已下载的  ``lombok.jar``  文件。
image::images/properties1.png[title=""Properties"（属性）窗口中的 "Libraries"（库）类别"]

在 "Compile"（编译）标签上添加的资源对应于 link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html#options[+Java 编译器+]的  ``-classpath``  选项。鉴于  ``lombok.jar``  是一个同时包含标注定义和标注处理程序的单一 JAR 文件，您应该在 "Compile"（编译）标签中将其添加到项目的类路径中。


. 在 "Project Properties"（项目属性）窗口中，选择 "Compiling"（编译）类别。


. 确认选中了 "Enable Annotation Processing"（启用标注处理）复选框（默认为启用），然后选择 "Enable Annotation Processing in Editor"（在编辑器中启用标注处理）复选框。
image::images/properties2.png[title=""Properties"（属性）窗口中的 "Compiling"（编译）类别"]

"Enable Annotation Processing"（启用标注处理）复选框使构建和编译项目期间可以进行标注处理。如果未选中该复选框，则会将  ``-proc:none``  选项传递给 Java 编译器，因此，编译时不进行任何标注处理。因此，如果要处理代码中的标注，则必须选中 "Enable Annotation Processing"（启用标注处理）复选框。

通过选中 "Enable Annotation Processing in Editor"（在编辑器中启用标注处理）复选框，可在编辑器中查看标注处理结果。标注处理程序生成的其他任何工件（类、方法、字段等）均会显示在 IDE 编辑器中，并且可用于代码完成、导航器、跳转类型、查找使用实例等。


. 在 "Project Properties"（项目属性）窗口单击 "OK"（确定），返回到  ``MyBooks.java``  文件。

如果在 "Projects"（项目）窗口中展开 "Libraries"（库）节点，则可以看到  ``lombok.jar``  现在被列为项目库。

image::images/projects-window.png[title=""Projects"（项目）窗口中的 "Libraries"（库）节点"]


== 编写使用 Lombok 定制标注的应用程序

1. 在  ``MyBooks.java``  文件的  ``MyBooks``  类声明前键入  ``@Data`` 。 ``@Data``  是一个为以下 Java 类生成样板代码的标注：所有字段的 getter、非最终字段的 setter 以及与调用该类字段相应的  ``toString`` 、 ``equals``  和  ``hashCode``  实现。

要了解有关 Project Lombok 支持的标注的详细信息，请参见 Lombok 的link:http://projectlombok.org/features/index.html[+功能概述+]。


. 单击编辑器左旁注中的提示，然后为  ``lombok.Data``  添加 import。
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;
    }
}
----

注：已生成所需的代码工件（如 getter、setter、toString 等），并且可以在 "Navigator"（导航器）窗口中看到它们。 ``@Data``  标注生成了典型类所需的所有样板代码。

image::images/nav.png[title="显示项目成员的 "Navigator"（导航器）窗口"]

还可以调用代码完成窗口（Ctrl-空格键），然后查看生成的工件是否可供选择。现在，我们看到项目已编译，生成的工件可以通过程序的其他部分调用。


. 打开包含 _main_ 方法的  ``TestBooks.java``  文件，并添加下面的代码（粗体）以创建  ``MyBooks``  类的新对象。

[source,java]
----

package testann;

public class TestBooks {

    public static void main(String[] args) {
        *MyBooks books = new MyBooks(2009, "My Beautiful Dream", "John Smith");*
    }
}
----


. 添加以下代码，以输出  ``books``  变量的值。

要返回值，我们调用  ``lombok.jar``  自动生成的 getter 方法。键入时，请注意代码完成窗口是否提供了自动生成的工件。


[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());*
    }
}
----


. 保存所做的更改。


. 在 "Projects"（项目）窗口中，右键单击项目节点，然后选择 "Run"（运行）（F6 键）。

运行应用程序时，应会显示以下输出，说明应用程序编译成功。

image::images/output.png[title="运行应用程序之后的 "Output"（输出）窗口"]

您可以看到，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[+发送有关此教程的反馈意见+]