lombok.GettingStarted

Overview
[|Project Lombok] uses a Java Annotation Processor and Java annotations to add boilerplate code to existing classes. The major IDEs also support Lombok in varying forms, making it viable for both command-line and IDE-based work. In this introduction, we'll begin by creating a project from scratch using a [|Maven Archetype] and then migrate it to use [|Project Lombok] and [|Slf4j]. Then we'll move on to seeing how it works in [|IntelliJ] and then we'll migrate the project to use [|Gradle].

Create a Basic Project
We need a project, since this is about a tool, the any project will do. To avoid much of the work, let's use a Maven archetype to create a trival project with a single production class and a single test class using JUnit.

First we'll create a place to put the project, then create the primordial project. For this example, I'll be working in my account: /Users/schuchert/src. Where I mention directories, remember to replace my directory with yours.

code format="bash" mkdir -p ~/src/lombok cd ~/src/lombok code
 * Create the top-level directory for a number of projects

code format="bash" mvn archetype:generate -DgroupId=com.shoe.lombok \ -DartifactId=gettingstarted \ -DarchetypeArtifactId=maven-archetype-quickstart \ -DinteractiveMode=false [INFO] Scanning for projects... [INFO] < > [INFO] [INFO] BUILD SUCCESS [INFO] [INFO] Total time: 29.869 s [INFO] Finished at: 2014-05-12T18:47:04-08:00 [INFO] Final Memory: 13M/130M [INFO] code
 * Use a maven archetype to create a basic project:

code format="bash" cd gettingstarted mvn test [INFO] Scanning for projects... [INFO] < > --- T E S T S --- Running com.shoe.lombok.AppTest Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.005 sec
 * Verify the basic project works

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] [INFO] BUILD SUCCESS [INFO] [INFO] Total time: 3.055 s [INFO] Finished at: 2014-05-12T18:49:18-08:00 [INFO] Final Memory: 14M/156M [INFO] code

Now we have basic project that uses Java and JUnit, so it's time to add Lombok to the project dependences and get things to work at the command line.

Adding Lombok
The project created by the Maven archetype has a simple POM. It has a single dependency on JUnit. We'll make 3 changes: update the version of JUnit, add a dependency for Lombok, and add a dependency for Slf4j.


 * Update the pom.xml file with the changed dependencies:

code format="xml" 
 * //pom.xml//**

4.0.0 com.shoe.lombok gettingstarted jar 1.0-SNAPSHOT gettingstarted http://maven.apache.org

org.projectlombok lombok 1.12.6

org.slf4j slf4j-api 1.7.7

junit</groupId> junit</artifactId> 4.11      test

code

code format="bash" vi `find. -name App.java` code
 * Gently start to use Lombok by introducing a logger. The project has one production class, App.java. Open that file and update as shown (note, since I'm still working at the command line, here's a command to edit that file:


 * Make two updates, add an annotation and update the line that writes to the console:

code format="java" package com.shoe.lombok;
 * //App.java//**

import lombok.extern.slf4j.Slf4j;

@Slf4j public class App {   public static void main( String[] args ) {       log.debug( "Hello World!" ); } } code

code format="bash" mvn test [INFO] Scanning for projects... [INFO] < > --- T E S T S --- Running com.shoe.lombok.AppTest Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.037 sec
 * Verify that the project still builds by re-running the tests:

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] [INFO] BUILD SUCCESS [INFO] [INFO] Total time: 1.110 s [INFO] Finished at: 2014-05-12T19:02:51-08:00 [INFO] Final Memory: 7M/156M [INFO] code

Note, while the test created by the maven archetype doesn't directly test what we changed, the code as written will not compile if the annotation processor is not in place. If you are a healthy skeptic like me, you might want to verify this assertion. Verify by removing the dependency on lombok and see if the tests still pass (note use of "clean" is necessary since we modified the pom.xml file but not the Java code): code format="bash" mvn clean test [INFO] Scanning for projects... < > [INFO] Compiling 1 source file to /Users/schuchert/src/lombok/gettingstarted/target/classes [INFO] - [ERROR] COMPILATION ERROR : < > code

code format="bash" mvn test [INFO] Scanning for projects... [INFO] < > --- T E S T S --- Running com.shoe.lombok.AppTest Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.036 sec
 * Restore the dependency and try again last time:

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] [INFO] BUILD SUCCESS [INFO] [INFO] Total time: 1.760 s [INFO] Finished at: 2014-05-12T19:08:16-08:00 [INFO] Final Memory: 13M/156M [INFO] code

Note that we did not need to use "clean" this time because the last attempt to build failed.

Is anything going on?
What this demonstrates may be trivial/subtle. To make sure you didn't miss it, consider the production code again:

code format="java" package com.shoe.lombok;
 * //App.java**//

import lombok.extern.slf4j.Slf4j;

@Slf4j public class App {   public static void main( String[] args ) {       log.debug( "Hello World!" ); } } code

Notice the line: code format="java" log.debug( "Hello World!" ); code

How can this code compile? There is not a local variable named log. There does not appear to be a field called log, yet the code compiles. What the Lombok annotation processor does is modify the source code to:
 * Introduce a static field called Log (that's an Slf4j logger due to the the @Slf4j annotation)
 * Initialize that field to an Slf4j logger

There are a number of annotations and there are even extensions to Lomboc for even more. However, sticking with just this one, how about working with an IDE?

Getting this to work in IntelliJ Idea
include page="sidebar_start"include page="TheSwitchToIdea" include page="sidebar_end"
 * Open the pom.xml in Idea 13.
 * Run the tests

Starting with a Maven project, Idea will open the project and execute tests fine. We get the same results using the command line and in the IDE. While Idea supports this out of the box, there are some irritating code inspection errors. To fix this, you can install the Lomboc plugin and those also disappear.

Gradle
What if you are using Gradle instead of Maven? This is a quick set of steps to accomplish the same thing using gradle.

code format="bash" gradle init
 * Create a build.gradle file. In the the gettingstarted directory:
 * wrapper
 * init

Maven to Gradle conversion is an incubating feature.

BUILD SUCCESSFUL

Total time: 4.951 secs code

Here's the generated build.gradle (a few blank lines removed):

code format="groovy" apply plugin: 'java' apply plugin: 'maven'
 * //build.gradle**//

group = 'com.shoe.lombok' version = '1.0-SNAPSHOT'

description = """gettingstarted"""

sourceCompatibility = 1.5 targetCompatibility = 1.5

repositories { maven { url "http://repo.maven.apache.org/maven2" } }

dependencies { compile group: 'org.projectlombok', name: 'lombok', version:'1.12.6' compile group: 'org.slf4j', name: 'slf4j-api', version:'1.7.7' testCompile group: 'junit', name: 'junit', version:'4.11' } code

code format="bash" gradle test
 * Run the tests and verify that they pass:
 * compileJava

warning: [options] bootstrap class path not set in conjunction with -source 1.5 1 warning
 * processResources UP-TO-DATE
 * classes
 * compileTestJava

warning: [options] bootstrap class path not set in conjunction with -source 1.5 1 warning
 * processTestResources UP-TO-DATE
 * testClasses
 * test

BUILD SUCCESSFUL

Total time: 7.526 secs code

code format="groovy" sourceCompatibility = 1.7 targetCompatibility = 1.7 code
 * Depending on the version of Java you are using, you might notice some warnings. In my system I'm using JDK 1.7 but the generated gradle file uses 1.5 as the expected version. To fix this, update to the appropriate version of Java you are using, which is 1.7 in my case::

code format="bash" gradle test --rerun-tasks
 * One more build should show those warnings disappear. Note the use of --rerun-tasks is necessary since the last build was a success:
 * compileJava
 * processResources UP-TO-DATE
 * classes
 * compileTestJava
 * processTestResources UP-TO-DATE
 * testClasses
 * test

BUILD SUCCESSFUL

Total time: 5.195 secs code

Gradle and Idea 13
Idea support for gradle improved quite a bit in Idea 13. However, the annotation processing is not so cleanly handled by Idea + Gradle. If you import the build.gradle project, you'll need to turn on annotation processing to make the code compile successfully. If you do not IntelliJ will respond with a compilation error: code Error:(10, 9) java: cannot find symbol symbol:  variable log location: class com.shoe.lombok.App code

Conclusion
We've created a simple application and introduced Lombok. The jar file for Lombok needs to be in the classpath during compilation when working at the command line. This happens naturally when using Maven or Gradle by depending on Lombok. In an IDE, there are different ways to accomplish that.