Installing Eclipse

Eclipse comes in several variants. To download any of them, go to https://www.eclipse.org/downloads/ or https://www.eclipse.org/downloads/packages/. We will use the Eclipse IDE for Enterprise Java Developers variant in this book.

In this book, we will use Eclipse version 2020-03, but you might be able to use higher versions. Just keep in mind that if you run into trouble without an obvious solution, downgrading to Eclipse 2020-03 is an option.

The chgrp ... command changes the group ownership and the chmod ... command allows write access for all group members. The usermod ... command adds a particular user to the new group.

This makes it easier to switch between different Eclipse versions on your system.

On a Windows system, the installer sets the access rights for you and it is normally possible for any normal user to install plugins . This depends on the Windows version and on your system’s configuration. Corporate environments often have more fine-grained access rights, with normal users who are unable to install plugins and to upgrade, and superusers for administrative purposes. These rights can be configured using Windows access rights management.

Configuring Eclipse

Don’t use escaped backslashes, like in C:\path\to\..., as you would expect for Java-related files!

In order to see which version Java Eclipse uses for running (not for building projects!), start Eclipse, then navigate to Help➤About Eclipse IDE➤Installation Details➤Configuration tab. In the pane, find the line that starts with java.runtime.version=....

Adding Java Runtimes

Eclipse itself is a Java application, and in the preceding section, we learned how to tell Eclipse which Java version to choose for its own interests. For the development itself, you have to tell Eclipse which Java version to use for compiling and running the applications it hosts.

To do so, note the paths of all JDK installations you want to use for Eclipse development. Then, start Eclipse.

Inside Eclipse, go to Window➤Preferences➤Java➤Installed JREs. Usually Eclipse is clever enough to automatically provide the JRE it used for its own startup. If this is enough for you, you don’t have to do anything here. Otherwise, click the Add... button to register more JREs. In the subsequent dialog, select Standard VM as the JRE type.

Select the check box to mark your primary JRE. Don’t forget to click the Apply or Apply and Close button to register your changes.

Adding Plugins

Eclipse can be extended by many useful plugins. Some of them are necessary for your development, and some just improve your development workflow. In this book, we won’t use too many extra plugins, and I will provide plugin installation instructions when they are needed.

As an exception, we will now install a Gradle plugin. We will later see that we can use Gradle from the console, but the Gradle plugin in Eclipse allows us to use Gradle directly from inside the IDE. Open Help➤Install New Software... and enter Eclipse Buildship (Gradle) and http://download.eclipse.org/buildship/updates/latest in the dialog. Select all the features and finish the wizard.

Eclipse Everyday Usage

A Basic Gradle Project

In order to learn more about Gradle, we build a simple EchoLibrary library with just one class and one method, printing a string to the console. Start Eclipse, and you’ll be asked for a workspace. Choose any folder of your choice.

Go to File➤New➤Other...➤Gradle➤Gradle Project. Choose EchoLibrary as the project name. You can use the default settings for the Gradle project options. Upon completion, the New Project wizard prepares the project and adds a few files to the project that holds the Gradle configuration.

The next thing we do is make sure the project can use an existing JSE installation. The Gradle project wizard might try to use a nonexistent JRE and an error marker will appear. See Figure 3-1.

To fix such a mismatch or to check whether the correct JRE is used, right-click the project, then choose Properties➤Java Build Path➤Libraries. See Figure 3-2.

If there is a mismatch, remove the invalid entry by clicking Classpath and then choosing Add Library...➤JRE System Library. Add the version 8 JRE you registered with Eclipse. Then click the Apply and Close button.

Gradle Main Concepts

Standard Gradle Project Layout

We will learn how to change the project structure in a later section.

The Central Gradle Build File

The Gradle project wizard from Eclipse creates a sample build.gradle file inside the project’s root folder. For any Gradle project, including projects that don’t use Eclipse, this is the central build file. The Eclipse plugin provides a basic build file with some example entries, but you can of course build this file from scratch.

A build file usually starts by defining which plugins are to be used, and then configures the plugins. User-defined tasks with operating instructions can also go to the build file, if needed. It is also possible to add Groovy or Kotlin code to existing tasks, which gives you the power to fine-tune plugins according to your needs.

Plugins usually have a very precise and reasonable idea about their defaults, so there is not much to configure for your project. For this reason, the build file could be rather small. This convention-over-configuration style is not an invention of Gradle, but Gradle—with its design aiming at elegance-gratefully adopts this idea.

The first three lines plugins { id 'java-library' } specify that we want to use the java-library plugin. The name tells all, we in fact want to build a Java library, but you can learn about the details in the plugins section of the user manual.

The java { sourceCompatibility = JavaVersion.VERSION_1_8; targetCompatibility = JavaVersion.VERSION_1_8 } settings specify the JRE version of our library. Possible values can be looked up in the org.gradle.api.JavaVersion class, but you won’t find anything surprising there (JDK 13 = JavaVersion.VERSION_1_13 and so on).

The repositories { jcenter() } lines indicate where Gradle will try to load libraries that your project depends on. The jcenter() points to Bintray’s JCenter, but you can also use google() for Android projects and mavenCentral() for Maven Central. Or, you could specify a custom URL, as in repositories { maven { url "http://my.company.com/myRepo" } }, which comes in handy with private or company-owned repositories. See the Gradle manual section called “Declaring Repositories.”

The dependencies section indicates which libraries our project needs. For the EchoLibrary example, we have no dependency to an external library, but for unit tests, which we did not write in this case but could very well be an exercise for the inclined reader, we add a dependency to the JUnit test library.

All other settings—like the position of the source files, how the generated JAR file is named and where it is written to, where to store and cache downloaded dependencies, and so on—are handled by the plugin defaults.

This build file with a handful of settings can now be used to perform various build tasks.

Running Gradle Tasks

Build-related and user-triggered activities in Gradle are called tasks. The main objective of Gradle from a handling perspective is about invoking tasks.

The Eclipse Gradle plugin has a Gradle Tasks and a Gradle Executions view. In addition, diagnostic output goes to the standard Console view. The two Gradle-related views open by default after you install the Gradle plugin. See Figure 3-3.

If this is not the case for you, go to Window➤Show View➤Other...➤Gradle to open a Gradle view. The Console view is available from Window➤Show View➤Console.

The Gradle Tasks view lists all available tasks in a tree view; see Figure 3-4. The scope of the tasks shown can be filtered using the view menu (small down triangle in the menu). If you introduce any custom tasks, this is a good time to enable the Show All Tasks item; otherwise, the custom tasks don’t show up in the list. See Figure 3-5.

In order to run a Gradle task from inside the Gradle Tasks view, you first have to locate it inside the tree. Depending on how precise your idea is where to look inside the tree, you can also use the menu filter to find a task. Once you find it, double-click it to run the task. Diagnostic output, including any error messages, is shown in both the Gradle Executions and the Console views.

Tasks might have option parameters that control their functioning. For example, there is a tasks task that lists only a certain subset of all tasks. More precisely, tasks have a group property, and one of the groups is called other. If you run the tasks task without a parameter, tasks belonging to the other group are not included in the output. To show all tasks using that command, you must add an --all parameter. To do so from Eclipse, go to Run➤Run Configurations, navigate to Gradle Task, and add a new entry, as shown in Figure 3-6 (click the Add button twice to enter tasks and --all). Click Run and switch to the Console view to see the output.

For the EchoLibrary example, building a library JAR most probably is the main task. You can find it in the build section. Once you run it, the final JAR is presented in the build/libs folder.

Gradle Tasks Explained

Each plugin’s documentation may also describe more tasks of particular interest for that plugin.

Gradle Plugins

You can learn more about each plugin by looking into the Gradle user manual, specifically the chapter entitled “Gradle Plugin Reference.”

More About Repositories

Points to a Maven repository given an explicit URL. The precise syntax is

Points to an Ivy repository given an explicit URL. The precise syntax is

Uses the local Maven cache (usually in HOME-DIR/.m2)

For URLs you specify as repository locations, Gradle also supports the https:, file:, sftp:, and s3: (Amazon s3 services) protocols, or gcs: (Google cloud storage). The first three, and of course the standard http:// protocol, use the standard URL syntax. If needed, the Gradle manual explains more about the syntaxes for s3: and gcs.

This is for basic authentication. For more advanced authentication schemes, see the section called “Declaring Repositories” in the Gradle manual.

More About Dependencies

Dependencies in Gradle center on configurations. A (dependency-related) configuration is a dependency scope, which means it describes a usage scenario. Consider for example that you have one set of dependencies important only for testing, another set of dependencies needed for the internal functioning of some library, and yet another set of dependencies needed for internal functioning and forwarded to clients (because they show up in public method calls). All those are different scopes, or configurations.

(The noted dependency here is implementation com.sparkjava:spark-core:- 2.8.0.)

Changing the Project Structure

We learned that, by adhering to the default project structure, we don’t have to spend time in configuring the project, telling it where to find sources and resources.

Because all directory settings are specified as lists (seen from [ ... ]), you can also distribute sources and resources over several folders (use commas as separators).

The Gradle Build File Is a Groovy Script

Apart from the suspicious () in jcenter() and the strange mixture of A B and A = B constructs, this file might look like a configuration file with a syntax limited to setting some properties. The truth is much more gloomy, however. In fact, the build.gradle file is a Groovy script, and Groovy is a fully fledged scripting language running on top of a JVM engine.

Although we already stated that, for build definition files, a declarative programming style is preferable over a declarative programming style, it is, under certain circumstances, acceptable to add programming language constructs like conditional statements, switch constructs, loops, and calls to library objects for IO (files and the console), math, streams, date and time, and whatever else you might think of. Also, the { } brackets in the build files actually do not denote blocks, but closures. So the dependencies { } construct is actually a shortcut for dependencies( { } ), and any A B construct in fact is a method call A( B ).

You could now call any task with the extra option -Dadd.math added to see the conditional statement and console output working.

Script Variables

In order for the ${} substitution to work, the double quotation marks are required—this is a Groovy language feature (GString objects). Otherwise in Groovy you can use both single and double quotation marks to denote strings.

Custom Tasks

We can define our own tasks inside the build.gradle file. Because we can use the Groovy language inside the build script, the possibilities are endless here. We can add logging, include non-standard files in archives, perform encryption, deploy artifacts on servers, publish files in a non-standard way, perform timing, invoke extra preparation and cleanup steps, and more.

The group and description settings are both optional; the default for the group is other, and if you omit the description, an empty string will be taken instead. The possible values for group are build, build setup, documentation, help, verification, and other.

To execute a custom task, you do the same thing as you do for built-in tasks or tasks defined by plugins. However, in order for the Eclipse Gradle plugin to be able to see the new task, you first must right-click the project and then choose Gradle➤Refresh Gradle Project. Then you’ll see the new task in the tree view of the Gradle Tasks view and can execute it by double-clicking it.

The instructions inside the main { } are executed during the configuration phase. It is important to know that such instructions are executed unconditionally for all tasks declared! For task-execution matters, you instead put instructions into doFirst { } or doLast { }. Each task has an action list; if you use doFirst, instructions are prepended to the action list, if you use doLast, actions are appended to the action list.

The magic behind that is that any task is directly available by its name inside the build.gradle script. So, if you write build.dependsOn hello, any execution of the build task first leads to executing hello. In hello.dependsOn build, an execution of the hello task first yields a build execution. This way, it is possible to add task dependency relations to existing standard and non-standard tasks.

The Gradle Wrapper

gradlew and gradlew.bat are Gradle startup scripts for Linux and Windows, respectively. The gradle folder contains the standalone Gradle installation.

The Eclipse Gradle plugin does not use these wrapper scripts. Instead, upon starting the first Gradle task, a Gradle daemon from inside USER_HOME/gradle is started. This daemon runs in the background and any Gradle task execution triggered from Eclipse contacts this daemon for the actual build work. This allows for faster task executions.

If Gradle gets invoked from the console, the wrapper is used, and such a daemon process will be started as well. We talk about the console-oriented way of development in the “Developing Using the Console” section.

Multi-Project Builds

Gradle projects can have subprojects. Apart from gathering projects that exhibit some kind of inter-relation, such a hierarchy built of one main project and one or more subprojects also is important for EAR projects, where we typically have one web application, maybe some EJBs, and possibly some libraries.

Of course you can choose different names for the subprojects. Next, create two folders inside the project folder, with names proj1 and proj2 (or whatever names you have chosen). Add an empty build.gradle file to each of the new folders. You can later add any subproject-related build instructions there.

Right-click the project and choose Gradle➤Refresh Gradle Project. Eclipse will update the Project Explorer and show the main project and the two subprojects as different entries; see Figure 3-7.

Due to a bug in the Gradle plugin, you have to fix the JRE library assignment for all three entries. On each of them, right-click and then choose Properties➤Libraries. Remove the wrong entry, then click Add Library (to classpath)➤JRE System Library➤Workspace Default JRE (or whatever suits your needs). The error markers should now be gone, as shown in Figure 3-8.

You can read more about multi-project builds in the sections called “Configuring Multi-Project Builds” and “Authoring Multi-Project Builds” in the Gradle user manual. We will use a multi-project in Chapter 9.

Adding a Deploy Task

The tasks create a temporary password file; this is just the GlassFish way of avoiding manual password entry. The "...".execute() creates a process running on the operating system; for the Windows variant, we have to prepend a cmd /c.

We can now perform a deployment or “un-deployment” by invoking the localDeploy or localUndeploy task, respectively. Since we added a dependsOn: build as a task dependency for deployment, it is not necessary to build a deployable artifact; this is done automatically.