blob: d5beb886689807154ee1534d2f5cbfcac0d6221e [file] [log] [blame]
<!doctype html>
<html class="no-js" lang="en" dir="ltr">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title>Annotations, Part I: Using Project Lombok for Custom Annotations</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Annotation Processors Support in the NetBeans IDE, Part I: Using Project Lombok - Apache NetBeans">
<meta name="author" content="Apache NetBeans">
<meta name="description" content="Annotation Processors Support in the NetBeans IDE, Part I: Using Project Lombok - Apache NetBeans">
<meta name="keywords" content="Apache NetBeans, Tutorials, Annotation Processors Support in the NetBeans IDE, Part I: Using Project Lombok">
<meta name="generator" content="Apache NetBeans">
<link rel="stylesheet" href="../../../../../../_/css/font-awesome.min.css">
<link rel="alternate" type="application/atom+xml" title="Apache NetBeans Blog" href="https://netbeans.apache.org/blogs/atom" />
<link rel="stylesheet" href="../../../../../../_/css/highlightjs/default.min.css">
<link rel="stylesheet" href="../../../../../../_/css/netbeans.css">
<link rel="apple-touch-icon" sizes="180x180" href="../../../../../../_/images/fav/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="../../../../../../_/images/fav/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="../../../../../../_/images/fav/favicon-16x16.png">
<link rel="manifest" href="../../../../../../_/images/fav/site.webmanifest">
<link rel="mask-icon" href="../../../../../../_/images/fav/safari-pinned-tab.svg" color="#5bbad5">
<meta name="msapplication-TileColor" content="#ffc40d">
<meta name="theme-color" content="#ffffff">
<link href="../../../../../../_/css/font-open-sans.css" rel="stylesheet">
<!--
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.
-->
</head>
<body>
<div class="title-bar" data-responsive-toggle="responsive-menu" data-hide-for="medium">
<button type="button" data-toggle="responsive-menu"><i style='font-size: 32px; color: #fff; padding: 8px' class='fa fa-bars'></i></button>
<div class="title-bar-title">Apache NetBeans</div>
</div>
<div class="top-bar" id="responsive-menu">
<div class='top-bar-left'>
<a class='title' href="../../../../../../index.html"><img src='../../../../../../_/images/apache-netbeans.svg' style='padding: 8px; height: 48px;'> Apache NetBeans</a>
</div>
<div class="top-bar-right">
<ul class="vertical medium-horizontal menu" data-responsive-menu="drilldown medium-dropdown">
<li> <input id="search-input" type="text" placeholder="Search the docs"> </li>
<li> <a href="../../../../../../front/main/community">Community</a> </li>
<li> <a href="../../../../../../front/main/participate">Participate</a> </li>
<li> <a href="../../../../../../front/main/blogs">Blog</a></li>
<li> <a href="../../../../../../front/main/help">Get Help</a> </li>
<li> <a href="https://plugins.netbeans.apache.org/">Plugins</a> </li>
<li> <a href="../../../../../../front/main/download">Download</a> </li>
</ul>
</div>
</div>
<!-- src/templates/news -->
<section class="hero news alternate">
<div class='grid-container'>
<div class='cell'>
<div class="annotation">Latest release</div>
<h1>Apache NetBeans 27</h1>
<p><a class="button success" href="../../../../../../front/main/download/nb27">Download</a></p>
</div>
</div>
</section>
<div class='grid-container main-content tutorial'>
<article class="doc">
<h1 class="sect0">Annotations, Part I: Using Project Lombok for Custom Annotations</h1>
<div class="sectionbody">
<div class="admonitionblock note">
<table>
<tbody><tr>
<td class="icon"><i class="fa icon-note" title="Note"></i></td>
<td class="content">This tutorial needs a review.
You can <a href="https://github.com/apache/netbeans-antora-tutorials/edit/main/modules/ROOT/pages/kb/docs/java/annotations-lombok.adoc" title="Edit this tutorial in github">edit it in GitHub </a>
following these <a href="../../../../../../tutorial/main/kb/docs/contributing">contribution guidelines.</a></td>
</tr></tbody>
</table>
</div>
</div>
<div id="toc" class="toc">
<div id="toctitle"></div>
<ul class="sectlevel1">
<li><a href="#_requirements">Requirements</a></li>
<li><a href="#_creating_a_new_java_project">Creating a New Java project</a></li>
<li><a href="#_enabling_custom_annotations_lombok_jar_for_the_project">Enabling Custom Annotations (lombok.jar) for the Project</a></li>
<li><a href="#_writing_an_application_using_lombok_custom_annotations">Writing an Application Using Lombok Custom Annotations</a></li>
<li><a href="#_next_step">Next Step</a></li>
</ul>
</div>
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>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 <a href="https://projectlombok.org/">Project Lombok&#8217;s website</a>.
However, keep in mind that Project Lombok includes some features that might not work in all development environments.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_requirements"><a class="anchor" href="#_requirements"></a>Requirements</h2>
<div class="sectionbody">
<div class="paragraph">
<p>To complete this tutorial, you need the following software and resources.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 75%;">
<col style="width: 25%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Software or Resource</th>
<th class="tableblock halign-left valign-top">Version Required</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://netbeans.org/download/index.html">NetBeans IDE</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">9.0 or later</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development Kit (JDK)</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">version 7 or 8</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://projectlombok.org/download">lombok.jar</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.12.4 or newer</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect1">
<h2 id="_creating_a_new_java_project"><a class="anchor" href="#_creating_a_new_java_project"></a>Creating a New Java project</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In this exercise you create a simple Java project and class that is named <code>MyBooks.java</code> which will demonstrate annotations in action.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Choose <em>File &gt; New Project</em> from the main menu to open the New Project wizard.</p>
</li>
<li>
<p>Select the Java Application project type in the Java category. Click Next.</p>
</li>
<li>
<p>In the Name and Location page of the wizard, type <code>TestAnn</code> as the project name.</p>
</li>
<li>
<p>Type <code>testann.TestBooks</code> in the Create Main Class field to replace the default class name. Click Finish.</p>
<div class="imageblock">
<div class="content">
<img src="../../../../_images/kb/docs/java/newproj.png" alt="newproj">
</div>
<div class="title">Figure 1. Creating a new Java project in the NetBeans IDE</div>
</div>
<div class="paragraph">
<p>When you click Finish, the IDE creates the Java application project and opens the <code>TestBooks.java</code> class in the editor.
You can see that the new project is now visible in the Projects window and that the <code>TestBooks.java</code> class is in the <code>testann</code> package under the Source Packages node.</p>
</div>
</li>
<li>
<p>Right-click the <code>testann</code> package node in the Projects window and choose New &gt; Java class.</p>
</li>
<li>
<p>Type <code>MyBooks</code> for the Class Name and confirm that the class will be created in the <code>testann</code> package. Click Finish.</p>
<div class="paragraph">
<p>When you click Finish the IDE opens the new class in the editor.</p>
</div>
</li>
<li>
<p>In the source editor, add the following three fields to <code>MyBooks.java</code> .</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">package testann;
public class MyBooks {
<strong>private int year; //fields
private String title;
private String author;</strong>
}</code></pre>
</div>
</div>
</li>
<li>
<p>Place your insert cursor in the class declaration and press Ctrl-Space to invoke the editor&#8217;s code completion support.</p>
</li>
<li>
<p>Select <code>MyBooks (int year, String title, String author) - generate</code> in the code completion list to generate a constructor for <code>MyBooks.java</code> .</p>
<div class="imageblock">
<div class="content">
<img src="../../../../_images/kb/docs/java/generate-constructor.png" alt="generate constructor">
</div>
<div class="title">Figure 2. Code completion to generate constructor</div>
</div>
</li>
<li>
<p>Save your changes.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_enabling_custom_annotations_lombok_jar_for_the_project"><a class="anchor" href="#_enabling_custom_annotations_lombok_jar_for_the_project"></a>Enabling Custom Annotations (lombok.jar) for the Project</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In this exercise you will modify the project&#8217;s properties window to add a library to the project&#8217;s classpath and enable annotation processing in the editor.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Download the <a href="https://projectlombok.org/download">lombok.jar</a> file and save it on your system.</p>
</li>
<li>
<p>Right-click the <code>TestAnn</code> project&#8217;s node and choose Properties.</p>
</li>
<li>
<p>Select the Libraries category in the Project Properties dialog.</p>
</li>
<li>
<p>Click Add JAR/Folder in the Compile tab and locate the <code>lombok.jar</code> file that you downloaded.</p>
<div class="imageblock">
<div class="content">
<img src="../../../../_images/kb/docs/java/properties1.png" alt="properties1">
</div>
<div class="title">Figure 3. Libraries category in Properties window</div>
</div>
<div class="paragraph">
<p>The resources added on the Compile tab correspond to the <code>-classpath</code> option of the <a href="http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html#options">Java compiler</a>.
As <code>lombok.jar</code> is a single JAR file that contains both annotation definitions and annotation processors, you should add it to the project&#8217;s classpath, which is the Compile tab.</p>
</div>
</li>
<li>
<p>Choose the Compiling category in the Project Properties window.</p>
</li>
<li>
<p>Confirm that the Enable Annotation Processing checkbox is selected (it is enabled by default) and select the Enable Annotation Processing in Editor checkbox.</p>
<div class="imageblock">
<div class="content">
<img src="../../../../_images/kb/docs/java/properties2.png" alt="properties2">
</div>
<div class="title">Figure 4. Compiling category in Properties window</div>
</div>
<div class="paragraph">
<p>The Enable Annotation Processing checkbox enables annotation processing while building and compiling your project.
If the checkbox is not selected, the <code>-proc:none</code> 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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
</li>
<li>
<p>Click OK in the Project Properties window and return to the <code>MyBooks.java</code> file.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>If you expand the Libraries node in the Projects window, you can see that <code>lombok.jar</code> is now listed as a project library.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../../../_images/kb/docs/java/projects-window.png" alt="projects window">
</div>
<div class="title">Figure 5. Libraries node in Projects window</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_writing_an_application_using_lombok_custom_annotations"><a class="anchor" href="#_writing_an_application_using_lombok_custom_annotations"></a>Writing an Application Using Lombok Custom Annotations</h2>
<div class="sectionbody">
<div class="olist arabic">
<ol class="arabic">
<li>
<p>In <code>MyBooks.java</code> file, type <code>@Data</code> before the <code>MyBooks</code> class declaration. <code>@Data</code> is an annotation that generates
the boilerplate code for Java classes: getters for all fields, setters for all non-final fields, and appropriate <code>toString</code> , <code>equals</code> , and <code>hashCode</code>
implementations that involve the fields of the class.</p>
<div class="paragraph">
<p>To learn more about what annotations are supported by Project Lombok, refer to the Lombok <a href="https://projectlombok.org/features/index.html">Features Overview</a>.</p>
</div>
</li>
<li>
<p>Click the hint in the editor&#8217;s left margin and add import for <code>lombok.Data</code> .</p>
<div class="imageblock">
<div class="content">
<img src="../../../../_images/kb/docs/java/import-lombok.png" alt="import lombok">
</div>
<div class="title">Figure 6. Hint in editor to import lombok</div>
</div>
<div class="paragraph">
<p>The resulting code in the Editor should look like the example below.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="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;
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that necessary code artifacts, such as getters, setters, toString, etc, have been generated and you can see them in the Navigator window. The <code>@Data</code> annotation generated all the boilerplate code that is needed for a typical class.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../../../_images/kb/docs/java/nav.png" alt="nav">
</div>
<div class="title">Figure 7. Navigator window showing project members</div>
</div>
<div class="paragraph">
<p>You can also invoke the code completion window (Ctrl-Space) and see that the generated artifacts are available for picking them. Now, let&#8217;s see that the project compiles and the generated artifacts can be called from other parts of the program.</p>
</div>
</li>
<li>
<p>Open the <code>TestBooks.java</code> file with the <em>main</em> method and add the following code (in bold) to create a new object of the <code>MyBooks</code> class.</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">package testann;
public class TestBooks {
public static void main(String[] args) {
<strong>MyBooks books = new MyBooks(2009, "My Beautiful Dream", "John Smith");</strong>
}
}</code></pre>
</div>
</div>
</li>
<li>
<p>Add the following code to print out the values of the <code>books</code> variable.</p>
<div class="paragraph">
<p>To return the values, we call the getter methods that were auto-generated by <code>lombok.jar</code> . While you are typing, note that the auto-generated artifacts are available from the code completion window.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">package testann;
public class TestBooks {
public static void main(String[] args) {
MyBooks books = new MyBooks(2009, "My Beautiful Dream", "John Smith");
<strong>System.out.println("Year: " + books.getYear() + ", Title: " + books.getTitle() + ", Author: " + books.getAuthor());</strong>
}
}</code></pre>
</div>
</div>
</li>
<li>
<p>Save your changes.</p>
</li>
<li>
<p>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.</p>
<div class="imageblock">
<div class="content">
<img src="../../../../_images/kb/docs/java/output.png" alt="output">
</div>
<div class="title">Figure 8. Output window after running the application</div>
</div>
<div class="paragraph">
<p>You can see that the artifacts generated by the Lombok annotation processor are accessible from other parts of the program.</p>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_next_step"><a class="anchor" href="#_next_step"></a>Next Step</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p><a href="../annotations-custom/" class="xref page">Part II: Using Own Custom Annotation Processor in the IDE</a></p>
</li>
<li>
<p>Java SE Documentation - <a href="http://download.oracle.com/javase/6/docs/technotes/guides/language/annotations.html">Annotations</a></p>
</li>
<li>
<p>Java SE Tutorial - <a href="http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html">Annotations</a></p>
</li>
</ul>
</div>
</div>
</div>
<section class='tools'>
<ul class="menu align-center">
<li><a title="Facebook" href="https://www.facebook.com/NetBeans"><i class="fa fa-md fa-facebook"></i></a></li>
<li><a title="Twitter" href="https://twitter.com/netbeans"><i class="fa fa-md fa-twitter"></i></a></li>
<li><a title="Github" href="https://github.com/apache/netbeans"><i class="fa fa-md fa-github"></i></a></li>
<li><a title="YouTube" href="https://www.youtube.com/user/netbeansvideos"><i class="fa fa-md fa-youtube"></i></a></li>
<li><a title="Atom Feed" href="https://netbeans.apache.org/blogs/atom"><i class="fa fa-mf fa-rss"></i></a></li>
<li><a title="Slack" href="https://tinyurl.com/netbeans-slack-signup/"><i class="fa fa-md fa-slack"></i></a></li>
<li><a title="Issues" href="https://github.com/apache/netbeans/issues"><i class="fa fa-mf fa-bug"></i></a></li>
</ul>
<ul class="menu align-center">
<li><a href="https://github.com/apache/netbeans-antora-tutorials/edit/main/modules/ROOT/pages/kb/docs/java/annotations-lombok.adoc" title="See this page in github"><i class="fa fa-md fa-edit"></i> See this page in GitHub.</a></li>
</ul>
</section>
</article>
</div>
<div class='grid-container incubator-area' style='margin-top: 64px'>
<div class='grid-x grid-padding-x'>
<div class='large-auto cell text-center'>
<a href="https://www.apache.org/">
<img style="height: 60px" title="Apache Software Foundation" src="../../../../../../_/images/asf_logo_wide.svg" />
</a>
</div>
<div class='large-auto cell text-center'>
<a href="https://www.apache.org/events/current-event.html">
<img style="width:234px; height: 60px;" title="Apache Software Foundation current event" src="https://www.apache.org/events/current-event-234x60.png"/>
</a>
</div>
</div>
</div>
<footer>
<div class="grid-container">
<div class="grid-x grid-padding-x">
<div class="large-auto cell">
<h1><a href="../../../../../../front/main/about">About</a></h1>
<ul>
<li><a href="../../../../../../front/main/community/who">Who's Who</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="https://www.apache.org/security/">Security</a></li>
</ul>
</div>
<div class="large-auto cell">
<h1><a href="../../../../../../front/main/community">Community</a></h1>
<ul>
<li><a href="../../../../../../front/main/community/mailing-lists">Mailing lists</a></li>
<li><a href="../../../../../../front/main/community/committer">Becoming a committer</a></li>
<li><a href="../../../../../../front/main/community/events">NetBeans Events</a></li>
<li><a href="https://www.apache.org/events/current-event.html">Apache Events</a></li>
</ul>
</div>
<div class="large-auto cell">
<h1><a href="../../../../../../front/main/participate">Participate</a></h1>
<ul>
<li><a href="../../../../../../front/main/participate/submit-pr">Submitting Pull Requests</a></li>
<li><a href="../../../../../../front/main/participate/report-issue">Reporting Issues</a></li>
<li><a href="../../../../../../front/main/participate/#documentation">Improving the documentation</a></li>
</ul>
</div>
<div class="large-auto cell">
<h1><a href="../../../../../../front/main/help">Get Help</a></h1>
<ul>
<li><a href="../../../../../../front/main/help/#documentation">Documentation</a></li>
<li><a href="../../../../../../wiki/main/wiki">Wiki</a></li>
<li><a href="../../../../../../front/main/help/#support">Community Support</a></li>
<li><a href="../../../../../../front/main/help/commercial-support">Commercial Support</a></li>
</ul>
</div>
<div class="large-auto cell">
<h1><a href="../../../../../../front/main/download">Download</a></h1>
<ul>
<li><a href="../../../../../../front/main/download">Releases</a></li>
<li><a href="https://plugins.netbeans.apache.org/">Plugins</a></li>
<li><a href="../../../../../../front/main/download/#_daily_builds_and_building_from_source">Building from source</a></li>
<li><a href="../../../../../../front/main/download/#_older_releases">Previous releases</a></li>
</ul>
</div>
</div>
</div>
</footer>
<div class='footer-disclaimer'>
<div class="footer-disclaimer-content">
<p>Copyright &copy; 2017-2025 <a href="https://www.apache.org">The Apache Software Foundation</a>.</p>
<p>Licensed under the Apache <a href="https://www.apache.org/licenses/">license</a>, version 2.0</p>
<div style='max-width: 40em; margin: 0 auto'>
<p>Apache, Apache NetBeans, NetBeans, the Apache feather logo and the Apache NetBeans logo are trademarks of <a href="https://www.apache.org">The Apache Software Foundation</a>.</p>
<p>Oracle and Java are registered trademarks of Oracle and/or its affiliates.</p>
<p>The Apache NetBeans website conforms to the <a href="https://privacy.apache.org/policies/privacy-policy-public.html">Apache Software Foundation Privacy Policy</a></p>
</div>
</div>
</div>
<script src="../../../../../../_/js/vendor/lunr.js"></script>
<script src="../../../../../../_/js/search-ui.js" id="search-ui-script" data-site-root-path="../../../../../.." data-snippet-length="100" data-stylesheet="../../../../../../_/css/search.css"></script>
<script async src="../../../../../../search-index.js"></script>
<script src="../../../../../../_/js/vendor/jquery.min.js"></script>
<script src="../../../../../../_/js/vendor/what-input.min.js"></script>
<script src="../../../../../../_/js/vendor/foundation.min.js"></script>
<script src="../../../../../../_/js/vendor/jquery.colorbox-min.js"></script>
<script src="../../../../../../_/js/netbeans.js"></script>
<script>
$(function(){ $(document).foundation(); });
</script>
<script src="../../../../../../_/js/vendor/highlight.min.js"></script>
<script>
document.addEventListener('DOMContentLoaded', (event) => {
document.querySelectorAll('pre code').forEach((el) => {
hljs.highlightElement(el);
});
});
</script>
</body>
</html>