netbeans.apache.org/src/content/kb/docs/java/annotations.asciidoc

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

= Annotation Processors Support in the NetBeans IDE
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
: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.

The link:annotations-lombok.html[+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 link:annotations-custom.html[+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

To complete this tutorial, you need the following software and resources.

[cols="3,1"]
|===
|Software or Resource |Version Required 

|link:https://netbeans.apache.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 
|===


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

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+]

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 link:../javaee/javaee-gettingstarted.html[+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+].

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"]
|===
|Java 6 javac Options |IDE Command |Description 

| ``-processor``  |

Project Properties > Build > Compiling > Annotation Processors field.

Specify a fully qualified name of the annotation processor in the Annotation Processors field.

 |Explicitly specifies the annotation processor to run. This option eliminates the need to create service provider-configuration files (META-INF/services/javax.annotation.processing.Processor) 

| ``-proc:none``  |

Project Properties > Build > Compiling > Enable Annotation Processing checkbox

When the checkbox is disabled, the project is compiled without any annotation processing.

 |Compilation proceeds without any annotation processing. The annotation processor discovery mechanism is not used during compilation. 

| ``-processorpath``  |

Project Properties > Libraries > Processor tab

Specify the path to an IDE project, library or a JAR file that contains an annotation processor. Use this option if an annotation processor and annotations are packaged into separate JAR files.

 |Specifies where to find annotation processors; if this option is not given, the classpath is searched for processors (see below). 

| ``-classpath``  |

Project Properties > Libraries > Compile tab

Specify the path to an IDE project, library or a JAR file that contains an annotation processor and annotation declarations. Use this option if an annotation processor and annotations are packaged into a single JAR file.

 |Specifies where to find user class files, and (optionally) annotation processors and source files. This path is searched for annotation processors if the -processorpath option is not specified. 

| ``-A_key[=value]_``  |

Project Properties > Build > Compiling > Processor Options field

Add options that should be passed to the annotation processor associated with your project. This value is optional.

 |(Optional) Options to pass to annotation processors. 
|===

 
== Next Steps

Read the following parts of the tutorial to learn how to use annotations in the IDE.

* link:annotations-lombok.html[+Part I: Using Project Lombok for Custom Annotations+]
* link:annotations-custom.html[+Part II: Using Own Custom Annotation Processor in the IDE+]