fix annotation tuto
diff --git a/modules/ROOT/pages/kb/docs/java/annotations-custom.adoc b/modules/ROOT/pages/kb/docs/java/annotations-custom.adoc
index 31c234e..da710c7 100644
--- a/modules/ROOT/pages/kb/docs/java/annotations-custom.adoc
+++ b/modules/ROOT/pages/kb/docs/java/annotations-custom.adoc
@@ -35,11 +35,13 @@
The previous part of the annotations tutorial (xref:kb/docs/java/annotations-lombok.adoc[Part I: Using Lombok for Custom Annotations]) showed how custom annotations work within NetBeans.
-In this section of the tutorial, you will learn how to add a self-written custom annotation processor to a project in the IDE. This tutorial does not teach you how to write an annotation processor. It explains how to add it to a NetBeans IDE project.
+In this section of the tutorial, you will learn how to add a self-written custom annotation processor to a project in the IDE.
+This tutorial does not teach you how to write an annotation processor. It explains how to add it to a NetBeans IDE project.
-The sample application used in this section was created by Jesse Glick and published as an xref:wiki::wiki/FaqApt.adoc[+FAQ entry+] for the previous IDE releases.
+The sample application used in this section was created by Jesse Glick and published as an xref:wiki::wiki/FaqApt.adoc[FAQ entry] for the previous IDE releases.
-The annotation processor used as the example generates a parent class for the annotated class. The generated parent class also contains a method that is called from the annotated class. Follow the instructions below on how to create and add a custom annotation processor to an IDE's project.
+The annotation processor used as the example generates a parent class for the annotated class. The generated parent class also contains a method that is called from the annotated class.
+Follow the instructions below on how to create and add a custom annotation processor to an IDE's project.
== Requirements
@@ -49,11 +51,11 @@
|===
|Software or Resource |Version Required
-|link:https://netbeans.org/download/index.html[+NetBeans IDE+] | 9.0 or greater
+|link:https://netbeans.org/download/index.html[NetBeans IDE] | 9.0 or greater
-|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+Java Development Kit (JDK)+] |version 6 or greater
+|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java Development Kit (JDK)] |version 6 or greater
-|link:http://code.google.com/p/projectlombok/downloads/list[+lombok.jar+] |v1.12.4 or newer
+|link:https://projectlombok.org/download[lombok.jar] |v1.12.4 or newer
|===
@@ -61,43 +63,27 @@
In this exercise you will create a class library project.
-1. Choose File > New Project and select the Java Class Library project type in the Java category. Click Next.
-2. Type ``AnnProcessor`` as the Project Name and specify a location for the project. Click Finish.
-
+. Choose File > New Project and select the Java Class Library project type in the Java category. Click Next.
+. Type ``AnnProcessor`` as the Project Name and specify a location for the project. Click Finish.
++
When you click Finish, the IDE creates the class library project and lists the project in the Projects window.
-
-
-
-
. Right-click the AnnProcessor project node in the Projects window and choose Properties.
-
-
. In the Sources category, confirm that either JDK 6 or JDK 7 are specified as the source/binary format.
-
-
. Select the Libraries tab and confirm that the Java platform is set to either JDK 1.6 or JDK 1.7. Click OK to close the Project Properties window.
In this exercise you will create two Java packages and one Java class in each of the packages.
-1. Right-click the Source Packages node under the AnnProcessor project node and choose New > Java Package.
-2. Type ``ann`` for the Package Name and click Finish to create the new Java package.
-3. Repeat the two previous steps to create a Java package named ``proc``.
-
+. Right-click the Source Packages node under the AnnProcessor project node and choose New > Java Package.
+. Type ``ann`` for the Package Name and click Finish to create the new Java package.
+. Repeat the two previous steps to create a Java package named ``proc``.
++
After you create the two Java packages, the structure of the project should be similar to the following image.
-
++
image::kb/docs/java/packages.png[title="The structure of the project for the annotation processor."]
-
-
-
-
. Right-click the ``ann`` Java package and choose New > Java class.
-
-
. Type ``Handleable`` for the Class Name. Click Finish.
-
-
. Modify the new ``Handleable.java`` file to make the following changes. Save the file.
-
++
[source,java]
----
@@ -107,27 +93,18 @@
}
----
-
++
This is how annotations are declared, and it is quite similar to an interface declaration. The difference is that the ``interface`` keyword must be preceded with an ``at`` sign (@). This annotation is called ``Handleable`` .
-
++
TIP: In annotation declarations, you can also specify additional parameters, for example, what types of elements can be annotated, e.g. classes or methods. You do this by adding ``@Target(value = {ElementType.TYPE})`` for classes and ``@Target(value = {ElementType.METHOD}).`` So, the annotation declaration becomes annotated itself with _meta-annotations_.
-
++
You now need to add code for the annotation processor to process the ``Handleable`` annotation.
-
-
-
-
. Right-click the ``proc`` Java package and choose New > Java class.
-
-
. Type ``HandleableProcessor`` for the Class Name. Click Finish.
-
-
. Modify the ``HandleableProcessor.java`` class to add the following code. Save your changes.
-
++
NOTE: The value of ``@SupportedSourceVersion`` will depend upon the version of the JDK that you are using and will be either ``(SourceVersion.RELEASE_7)`` or ``(SourceVersion.RELEASE_6)`` .
-
-
++
[source,java]
----
@@ -209,22 +186,20 @@
}
}
----
-
++
Let's take a closer look at the main parts that constitute the code for the annotation processor (note that for convenience, only parts of the code are provided).
-
++
At first, you specify the annotation types that the annotation processor supports (by using ``@SupportedAnnotationTypes`` ) and the version of the source files that are supported (by using ``@SupportedSourceVersion`` ), in this case the version is JDK 6:
-
-
++
[source,java]
----
@SupportedAnnotationTypes("ann.Handleable")
@SupportedSourceVersion(SourceVersion.RELEASE_6)
----
-
++
Then, you declare a public class for the processor that extends the ``AbstractProcessor`` class from the ``javax.annotation.processing`` package. ``AbstractProcessor`` is a standard superclass for concrete annotation processors that contains necessary methods for processing annotations.
-
-
++
[source,java]
----
@@ -232,10 +207,9 @@
...
}
----
-
++
You now need to provide a public constructor for the class.
-
-
++
[source,java]
----
@@ -246,10 +220,9 @@
}
----
-
++
Then, you call the ``process`` () method of the parent ``AbstractProcessor`` class. Through this method the annotations available for processing are provided. In addition, this method contains information about the round of processing.
-
-
++
[source,java]
----
@@ -261,10 +234,9 @@
}
}
----
-
++
The annotation processor's logic is contained within the ``process()`` method of the ``AbstractProcessor`` class. Note that through ``AbstractProcessor`` , you also access the ``ProcessingEnvironment`` interface, which allows annotation processors to use several useful facilities, such as Filer (a filer handler that enables annotation processors to create new files) and Messager (a way for annotation processors to report errors).
-
-
++
[source,java]
----
@@ -320,10 +292,9 @@
...
}
----
-
++
The last block in this code declares the ``capitalize`` method that is used to capitalize the name of the annotated element.
-
-
++
[source,java]
----
@@ -337,10 +308,6 @@
}
}
----
-
-
-
-
. Build the project by right-clicking the ``AnnProcessor`` project and choosing Build.
@@ -348,20 +315,14 @@
In this section you will create a Java Application project in which the annotation processor will be used.
-1. Choose File > New Project and select the Java Application project type in the Java category. Click Next.
-2. In the Name and Location page, type ``Demo`` as the Project Name and specify the project location.
-3. Type ``demo.Main`` in the Create Main Class field. Click Finish.
-
+. Choose File > New Project and select the Java Application project type in the Java category. Click Next.
+. In the Name and Location page, type ``Demo`` as the Project Name and specify the project location.
+. Type ``demo.Main`` in the Create Main Class field. Click Finish.
++
image::kb/docs/java/demo-project-wizard.png[title="Creating the Demo project in the New Project wizard."]
-
-
-
-
. Open the Project Properties window and confirm that either JDK 6 or JDK 7 are selected as the source/binary format in the Sources panel and that the Java platform is set to JDK 1.6 or JDK 1.7 in the Libraries panel.
-
-
. Modify the ``Main.java`` class to add the following code. Save your changes.
-
++
[source,java]
----
@@ -379,63 +340,45 @@
}
}
----
-
++
This code contains the following elements:
-
++
* import statement for the custom annotation processor ``ann.Handleable``
* the public class ``Main`` that extends the ``MainExtras`` class ( ``MainExtras`` should be generated by the annotation processor during compilation)
* a private field named ``stuff`` that is annotated with the ``@Handleable`` annotation
* the ``main`` method that calls the ``handleStuff`` method, which is declared in the automatically generated ``MainExtras`` class
-
++
In this simple example, the ``handleStuff`` method only prints out the current value. You can modify this method to perform other tasks.
-
++
After you save the ``Main.java`` code you will see that the IDE reports multiple compilation errors. This is because the annotation processor has not been added yet to the project.
-
-
-
-
++
. Right-click the ``Demo`` project node in the Projects window, choose Properties, then select the Libraries category in the Project Properties window.
-
-
. In the Compile tab, click Add Project and locate the ``AnnProcessor`` project.
-
++
image::kb/docs/java/demo-properties-compile.png[title="Compile tab in Libraries category of the project's Properties window"]
-
-The Compile tab corresponds to the ``-classpath`` option of the link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html#options[+Java compiler+]. Because the annotation processor is a single JAR file that contains both the annotation definition and the annotation processor, you should add it to the project's classpath, which is the Compile tab.
-
-
-
-
++
+The Compile tab corresponds to the ``-classpath`` option of the link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html#options[Java compiler].
+Because the annotation processor is a single JAR file that contains both the annotation definition and the annotation processor,
+you should add it to the project's classpath, which is the Compile tab.
. Select the Compiling category in the Project Properties window and select the Enable Annotation Processing and Enable Annotation Processing in Editor checkboxes.
-
-
. Specify the annotation processor to run by click the Add button next to the Annotation Processors text area and typing * ``proc.HandleableProcessor`` * in the Annotation Processor FQN field.
-
++
image::kb/docs/java/demo-processor-fqn.png[title="Annotation Processor FQN dialog box"]
-
++
The Compiling category in the Project Properties window should look like the following image.
-
++
image::kb/docs/java/demo-properties-compiling.png[title="Compiling category in the project's Properties window"]
-
-
-
-
. Click OK in the Properties window.
-
++
NOTE: In the ``Main.java`` file you might still see compilation errors. This is because the IDE cannot yet find the ``MainExtras.java`` file that declares the ``handleStuff`` method. The ``MainExtras.java`` file will be generated after you build the Demo project for the first time. If Compile On Save is enabled for you project, the IDE compiled the project when you saved ``Main.java`` .
-
-
-
-
. Right-click the Demo project and choose Build.
-
++
After you build the project, if you look at the project in the Projects window you can see a new ``Generated Sources`` node with the ``demo/MainExtras.java`` file.
-
++
image::kb/docs/java/demo-generated-sources.png[title="Projects window with Generated Sources"]
-
++
If you review the contents of the generated ``MainExtras.java`` file, you can see that the annotation processor generated the ``MainExtras`` class with the ``handleStuff`` method. The ``handleStuff`` method is the one invoked from the annotated ``Main.java`` file.
-
-
++
[source,java]
----
@@ -448,14 +391,10 @@
}
}
----
-
-
-
-
. Right-click the Demo project and choose Run.
-
++
When you click Run you should see the following in the Output window. The Demo project compiles and prints the message.
-
++
image::kb/docs/java/demo-run.png[title="Projects window with Generated Sources"]
== See Also
@@ -463,8 +402,8 @@
See the following resources for more information about annotations in Java applications:
* The previous part of the annotations tutorial: xref:kb/docs/java/annotations-lombok.adoc[Part I: Using Lombok for Custom Annotations]).
-* Java SE Documentation - link:http://download.oracle.com/javase/6/docs/technotes/guides/language/annotations.html[+Annotations+]
-* Java SE Tutorial - link:http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html[+Annotations+]
-* link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html#processing[+Java Compiler: Annotation Processing Options+]
-* link:http://blogs.oracle.com/darcy/[+Joseph D. Darcy's Weblog+] - useful tips from the JSR-269 specification lead
+* Java SE Documentation - link:http://download.oracle.com/javase/6/docs/technotes/guides/language/annotations.html[Annotations]
+* Java SE Tutorial - link:http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html[Annotations]
+* link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html#processing[Java Compiler: Annotation Processing Options]
+* link:http://blogs.oracle.com/darcy/[Joseph D. Darcy's Weblog] - useful tips from the JSR-269 specification lead
diff --git a/modules/ROOT/pages/kb/docs/java/annotations-lombok.adoc b/modules/ROOT/pages/kb/docs/java/annotations-lombok.adoc
index 2076634..1c00fc0 100644
--- a/modules/ROOT/pages/kb/docs/java/annotations-lombok.adoc
+++ b/modules/ROOT/pages/kb/docs/java/annotations-lombok.adoc
@@ -33,7 +33,12 @@
:imagesdir: ../../../../images
endif::[]
-To demonstrate how custom annotations work inside the NetBeans IDE, we will use Project Lombok, which provides a convenient way of automatically generating several Java code elements, such as getters, setters, constructors and others. For more information about its features, visit the link:http://projectlombok.org/[+Project Lombok's website+]. However, keep in mind that Project Lombok includes some features that might not work in all development environments.
+include::front::partial$database.adoc[]
+
+To demonstrate how custom annotations work inside the NetBeans IDE, we will use Project Lombok, which provides a convenient way of automatically generating
+several Java code elements, such as getters, setters, constructors and others.
+For more information about its features, visit the link:https://projectlombok.org/[Project Lombok's website].
+However, keep in mind that Project Lombok includes some features that might not work in all development environments.
== Requirements
@@ -43,11 +48,11 @@
|===
|Software or Resource |Version Required
-|link:https://netbeans.org/download/index.html[+NetBeans IDE+] | 9.0 or later
+|link:https://netbeans.org/download/index.html[NetBeans IDE] | 9.0 or later
-|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+Java Development Kit (JDK)+] |version 7 or 8
+|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java Development Kit (JDK)] |version 7 or 8
-|link:http://code.google.com/p/projectlombok/downloads/list[+lombok.jar+] |v1.12.4 or newer
+|link:https://projectlombok.org/download[lombok.jar] |v1.12.4 or newer
|===
@@ -55,30 +60,21 @@
In this exercise you create a simple Java project and class that is named ``MyBooks.java`` which will demonstrate annotations in action.
-1. Choose _File > New Project_ from the main menu to open the New Project wizard.
-2. Select the Java Application project type in the Java category. Click Next.
-3. In the Name and Location page of the wizard, type ``TestAnn`` as the project name.
-4. Type ``testann.TestBooks`` in the Create Main Class field to replace the default class name. Click Finish.
-
+. Choose _File > New Project_ from the main menu to open the New Project wizard.
+. Select the Java Application project type in the Java category. Click Next.
+. In the Name and Location page of the wizard, type ``TestAnn`` as the project name.
+. Type ``testann.TestBooks`` in the Create Main Class field to replace the default class name. Click Finish.
++
image::kb/docs/java/newproj.png[title="Creating a new Java project in the NetBeans IDE"]
-
-When you click Finish, the IDE creates the Java application project and opens the ``TestBooks.java`` class in the editor. You can see that the new project is now visible in the Projects window and that the ``TestBooks.java`` class is in the ``testann`` package under the Source Packages node.
-
-
-
-
++
+When you click Finish, the IDE creates the Java application project and opens the ``TestBooks.java`` class in the editor.
+You can see that the new project is now visible in the Projects window and that the ``TestBooks.java`` class is in the ``testann`` package under the Source Packages node.
. Right-click the ``testann`` package node in the Projects window and choose New > Java class.
-
-
. Type ``MyBooks`` for the Class Name and confirm that the class will be created in the ``testann`` package. Click Finish.
-
++
When you click Finish the IDE opens the new class in the editor.
-
-
-
-
. In the source editor, add the following three fields to ``MyBooks.java`` .
-
++
[source,java]
----
@@ -91,20 +87,11 @@
}
----
-
-
-
-
. Place your insert cursor in the class declaration and press Ctrl-Space to invoke the editor's code completion support.
-
-
. Select ``MyBooks (int year, String title, String author) - generate`` in the code completion list to generate a constructor for ``MyBooks.java`` .
-
++
image::kb/docs/java/generate-constructor.png[title="Code completion to generate constructor"]
-
-
-
-
++
. Save your changes.
@@ -112,34 +99,30 @@
In this exercise you will modify the project's properties window to add a library to the project's classpath and enable annotation processing in the editor.
-1. Download the link:http://code.google.com/p/projectlombok/downloads/list[+lombok.jar+] file and save it on your system.
-2. Right-click the ``TestAnn`` project's node and choose Properties.
-3. Select the Libraries category in the Project Properties dialog.
-4. Click Add JAR/Folder in the Compile tab and locate the ``lombok.jar`` file that you downloaded.
-
+. Download the link:https://projectlombok.org/download[lombok.jar] file and save it on your system.
+. Right-click the ``TestAnn`` project's node and choose Properties.
+. Select the Libraries category in the Project Properties dialog.
+. Click Add JAR/Folder in the Compile tab and locate the ``lombok.jar`` file that you downloaded.
++
image::kb/docs/java/properties1.png[title="Libraries category in Properties window"]
-
-The resources added on the Compile tab correspond to the ``-classpath`` option of the link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html#options[+Java compiler+]. As ``lombok.jar`` is a single JAR file that contains both annotation definitions and annotation processors, you should add it to the project's classpath, which is the Compile tab.
-
-
-
-
++
+The resources added on the Compile tab correspond to the ``-classpath`` option of the link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html#options[Java compiler].
+As ``lombok.jar`` is a single JAR file that contains both annotation definitions and annotation processors, you should add it to the project's classpath, which is the Compile tab.
. Choose the Compiling category in the Project Properties window.
-
-
. Confirm that the Enable Annotation Processing checkbox is selected (it is enabled by default) and select the Enable Annotation Processing in Editor checkbox.
-
++
image::kb/docs/java/properties2.png[title="Compiling category in Properties window"]
-
-The Enable Annotation Processing checkbox enables annotation processing while building and compiling your project. If the checkbox is not selected, the ``-proc:none`` option is passed to the Java compiler, and compilation takes places without any annotation processing. So, if you want to process annotations in your code, the Enable Annotation Processing checkbox must be selected.
-
-By selecting the Enable Annotation Processing in Editor checkbox, you make annotation processing results visible in the editor. Any additional artifacts that are generated by annotation processors (classes, methods, fields, etc.) become visible in the IDE Editor and available in code completion, Navigator, GoTo Type, Find usages, and others.
-
-
-
-
++
+The Enable Annotation Processing checkbox enables annotation processing while building and compiling your project.
+If the checkbox is not selected, the ``-proc:none`` option is passed to the Java compiler, and compilation
+takes places without any annotation processing. So, if you want to process annotations in your code, the Enable Annotation Processing checkbox must be selected.
++
+By selecting the Enable Annotation Processing in Editor checkbox, you make annotation processing results visible in the editor.
+Any additional artifacts that are generated by annotation processors (classes, methods, fields, etc.) become visible
+in the IDE Editor and available in code completion, Navigator, GoTo Type, Find usages, and others.
. Click OK in the Project Properties window and return to the ``MyBooks.java`` file.
+
If you expand the Libraries node in the Projects window, you can see that ``lombok.jar`` is now listed as a project library.
image::kb/docs/java/projects-window.png[title="Libraries node in Projects window"]
@@ -147,20 +130,17 @@
== Writing an Application Using Lombok Custom Annotations
-1. In ``MyBooks.java`` file, type ``@Data`` before the ``MyBooks`` class declaration. ``@Data`` is an annotation that generates the boilerplate code for Java classes: getters for all fields, setters for all non-final fields, and appropriate ``toString`` , ``equals`` , and ``hashCode`` implementations that involve the fields of the class.
-
-To learn more about what annotations are supported by Project Lombok, refer to the Lombok link:http://projectlombok.org/features/index.html[+Features Overview+].
-
-
-
-
+. In ``MyBooks.java`` file, type ``@Data`` before the ``MyBooks`` class declaration. ``@Data`` is an annotation that generates
+the boilerplate code for Java classes: getters for all fields, setters for all non-final fields, and appropriate ``toString`` , ``equals`` , and ``hashCode``
+implementations that involve the fields of the class.
++
+To learn more about what annotations are supported by Project Lombok, refer to the Lombok link:https://projectlombok.org/features/index.html[Features Overview].
. Click the hint in the editor's left margin and add import for ``lombok.Data`` .
-
++
image::kb/docs/java/import-lombok.png[title="Hint in editor to import lombok"]
-
++
The resulting code in the Editor should look like the example below.
-
-
++
[source,java]
----
@@ -183,19 +163,15 @@
}
}
----
-
++
Note that necessary code artifacts, such as getters, setters, toString, etc, have been generated and you can see them in the Navigator window. The ``@Data`` annotation generated all the boilerplate code that is needed for a typical class.
-
++
image::kb/docs/java/nav.png[title="Navigator window showing project members"]
-
++
You can also invoke the code completion window (Ctrl-Space) and see that the generated artifacts are available for picking them. Now, let's see that the project compiles and the generated artifacts can be called from other parts of the program.
-
-
-
-
. Open the ``TestBooks.java`` file with the _main_ method and add the following code (in bold) to create a new object of the ``MyBooks`` class.
-
-[source,java]
++
+[source,java,subs="{sourcesubs}"]
----
package testann;
@@ -207,16 +183,11 @@
}
}
----
-
-
-
-
. Add the following code to print out the values of the ``books`` variable.
-
++
To return the values, we call the getter methods that were auto-generated by ``lombok.jar`` . While you are typing, note that the auto-generated artifacts are available from the code completion window.
-
-
-[source,java]
++
+[source,java,subs="{sourcesubs}"]
----
package testann;
@@ -229,24 +200,17 @@
}
}
----
-
-
-
-
. Save your changes.
-
-
. Right-click the project node in the Projects window and choose Run (F6).
-
When you run the application you should see the following output that shows that the application compiled successfully.
-
++
image::kb/docs/java/output.png[title="Output window after running the application"]
-
++
You can see that the artifacts generated by the Lombok annotation processor are accessible from other parts of the program.
== Next Step
-* xref:kb/docs/java/annotations-custom.adoc[+Part II: Using Own Custom Annotation Processor in the IDE+]
-* Java SE Documentation - link:http://download.oracle.com/javase/6/docs/technotes/guides/language/annotations.html[+Annotations+]
-* Java SE Tutorial - link:http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html[+Annotations+]
+* xref:kb/docs/java/annotations-custom.adoc[Part II: Using Own Custom Annotation Processor in the IDE]
+* Java SE Documentation - link:http://download.oracle.com/javase/6/docs/technotes/guides/language/annotations.html[Annotations]
+* Java SE Tutorial - link:http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html[Annotations]
diff --git a/modules/ROOT/pages/kb/docs/java/annotations.adoc b/modules/ROOT/pages/kb/docs/java/annotations.adoc
index c4c9967..99c63e7 100644
--- a/modules/ROOT/pages/kb/docs/java/annotations.adoc
+++ b/modules/ROOT/pages/kb/docs/java/annotations.adoc
@@ -29,11 +29,16 @@
:description: Annotation Processors Support in the NetBeans IDE - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Annotation Processors Support in the NetBeans IDE
-This two-part tutorial demonstrates how you can attach annotation processors to a project and use them while working on your code in the IDE. NetBeans IDE includes built-in support for custom annotation processors. Now you can conveniently specify annotation processors to run with your project and see the results of annotation processing directly in the Java Editor through code completion and navigation.
+This two-part tutorial demonstrates how you can attach annotation processors to a project and use them while working on your code in the IDE.
+NetBeans IDE includes built-in support for custom annotation processors.
+Now you can conveniently specify annotation processors to run with your project and see the results of
+annotation processing directly in the Java Editor through code completion and navigation.
-The xref:kb/docs/java/annotations-lombok.adoc[+first part of the tutorial+] shows the use of the third-party annotation processor, link:http://projectlombok.org/[+Project Lombok+], in the NetBeans IDE.
+The xref:kb/docs/java/annotations-lombok.adoc[first part of the tutorial] shows the use of the third-party annotation processor,
+link:https://projectlombok.org/[Project Lombok], in the NetBeans IDE.
-The xref:kb/docs/java/annotations-custom.adoc[+second part of the tutorial+] provides explanations of how to add a self-written annotation processor to a project. The sample code for this part of the tutorial is contributed by Jesse Glick.
+The xref:kb/docs/java/annotations-custom.adoc[second part of the tutorial] provides explanations of how to add a self-written annotation processor to a project.
+The sample code for this part of the tutorial is contributed by Jesse Glick.
== Requirements
@@ -44,31 +49,46 @@
|===
|Software or Resource |Version Required
-|xref:front::download/index.adoc[+NetBeans IDE+] | 9.0 or later
+|xref:front::download/index.adoc[NetBeans IDE] | 9.0 or later
-|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+Java Development Kit (JDK)+] |version 7 or 8
+|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java Development Kit (JDK)] |version 7 or 8
|===
== Introduction
-_Annotations_ are a mechanism of the Java programming language that is used to hold metadata about the elements of your application. Annotations hold meta-information on how the annotated elements should be processed by the compiler, during deployment or at runtime. In other words, annotations are comments to your code that can be processed by other programs and tools.
+_Annotations_ are a mechanism of the Java programming language that is used to hold metadata about the elements of your application.
+Annotations hold meta-information on how the annotated elements should be processed by the compiler, during deployment or at runtime. In other words,
+annotations are comments to your code that can be processed by other programs and tools.
-You can use custom annotations to accomplish a variety of tasks: mark parts of your application (e.g. copyright information, test methods, etc.), automatically generate code, parse command-line options, develop web services, and others. The information on how custom annotations should be processed is passed to the Java compiler through custom annotation processors. link:http://www.jcp.org/en/jsr/detail?id=269[+JSR 269+] implemented in JDK 6 provides an official API for writing annotation processors. You can either write your own custom annotation processors or use third-party solutions.
+You can use custom annotations to accomplish a variety of tasks: mark parts of your application (e.g. copyright information, test methods, etc.),
+automatically generate code, parse command-line options, develop web services, and others.
+The information on how custom annotations should be processed is passed to the Java compiler through custom annotation processors.
+link:http://www.jcp.org/en/jsr/detail?id=269[JSR 269] implemented in JDK 6 provides an official API for writing annotation processors.
+You can either write your own custom annotation processors or use third-party solutions.
For starting information about annotations in JDK 6, refer to the following resources:
-* Java SE Documentation - link:http://download.oracle.com/javase/6/docs/technotes/guides/language/annotations.html[+Annotations+]
-* Java SE Tutorial - link:http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html[+Annotations+]
+* Java SE Documentation - link:http://download.oracle.com/javase/6/docs/technotes/guides/language/annotations.html[Annotations]
+* Java SE Tutorial - link:http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html[Annotations]
-In practice, annotations are most widely used in combination with Java Persistence API (JPA), which is part of the Java EE specification, and some other technologies, such as JAXB (Java Architecture for XML Binding). Using JPA, Java classes can be annotated as entities that later can be persisted to a storage. To develop JPA-based applications, it is convenient to use frameworks, for example, EclipseLink that is bundled with the IDE. As a starting point for more information on writing JPA-based applications in the NetBeans IDE, see xref:kb/docs/javaee/javaee-gettingstarted.adoc[+Getting Started with Java EE Applications+].
+In practice, annotations are most widely used in combination with Java Persistence API (JPA), which is part of the Java EE specification,
+and some other technologies, such as JAXB (Java Architecture for XML Binding). Using JPA, Java classes can be annotated as entities that later can be persisted to a storage.
+To develop JPA-based applications, it is convenient to use frameworks, for example, EclipseLink that is bundled with the IDE.
+As a starting point for more information on writing JPA-based applications in the NetBeans IDE,
+see xref:kb/docs/javaee/javaee-gettingstarted.adoc[Getting Started with Java EE Applications].
== Map of javac Options and IDE Commands for Annotation Processing
-As mentioned above, in Java SE 6 javac, annotation processing was incorporated as an integral functionality of the Java compiler. The compiler automatically searches for annotation processors by default at user class path (unless annotation processing is explicitly disabled). In addition, the search path or a path to particular annotation processors can be specified by using javac options. In the table below, you can see a map of the javac options related to annotation processing and the corresponding commands in the IDE. For more information on javac options in JDK 6, see link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html[+javac - Java programming language compiler+].
+As mentioned above, in Java SE 6 javac, annotation processing was incorporated as an integral functionality of the Java compiler.
+The compiler automatically searches for annotation processors by default at user class path (unless annotation processing is explicitly disabled).
+In addition, the search path or a path to particular annotation processors can be specified by using javac options.
+In the table below, you can see a map of the javac options related to annotation processing and the corresponding commands in the IDE.
+For more information on javac options in JDK 6, see link:http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html[javac - Java programming language compiler].
-NOTE: In the IDE, the annotation processing options for all Java application with the exception of NetBeans platform applications are specified in the Project Properties window. To open the project's Properties window window, right-click your project and choose Properties.
+NOTE: In the IDE, the annotation processing options for all Java application with the exception of NetBeans platform applications are specified in the Project Properties window.
+To open the project's Properties window window, right-click your project and choose Properties.
[cols="1,3,3"]
|===
@@ -120,6 +140,6 @@
Read the following parts of the tutorial to learn how to use annotations in the IDE.
-* xref:kb/docs/java/annotations-lombok.adoc[+Part I: Using Project Lombok for Custom Annotations+]
-* xref:kb/docs/java/annotations-custom.adoc[+Part II: Using Own Custom Annotation Processor in the IDE+]
+* xref:kb/docs/java/annotations-lombok.adoc[Part I: Using Project Lombok for Custom Annotations]
+* xref:kb/docs/java/annotations-custom.adoc[Part II: Using Own Custom Annotation Processor in the IDE]
