To work with the Java plugin, we are first going to create a very simple Java source file. We can then use the plugin's tasks to build the source file. You can make this application as complex as you wish, but in order to stay on topic, we will make this as simple as possible.
By applying the Java plugin, we must now follow some conventions for our project directory structure. To build the source code, our Java source files must be in the src/main/java directory, relative to the project directory. If we have non-Java source files that need to be included in the JAR file, we must place them in the directory src/main/resources. Our test source files need to be in the src/test/java directory, and any non-Java source files needed for testing can be placed in src/test/resources. These conventions can be changed if we want or need it, but it is a good idea to stick to them so we don't have to write any extra code in our build file, which could cause errors.
Our sample Java project we will write is a Java class that uses an external property file to get a welcome message. The source file with the name Sample.java is located in the src/main/java directory:
// File: src/main/java/gradle/sample/Sample.java
package gradle.sample;
import java.util.ResourceBundle;
/**
* Read welcome message from external properties file
* <code>messages.properties</code>.
*/
public class Sample {
public Sample() {
}
/**
* Get <code>messages.properties</code> file
* and read the value for <em>welcome</em> key.
*
* @return Value for <em>welcome</em> key
* from <code>messages.properties</code>
*/
public String getWelcomeMessage() {
final ResourceBundle resourceBundle = ResourceBundle.getBundle("messages");
final String message = resourceBundle.getString("welcome");
return message;
}
}In the code, we use ResourceBundle.getBundle() to read our welcome message. The welcome message itself is defined in a properties file with the name messages.properties, which will go in the src/main/resources directory:
# File: src/main/resources/gradle/sample/messages.properties welcome = Welcome to Gradle!
To compile the Java source file and process the properties file, we run the classes task. Note that the classes task has been added by the Java plugin. This is a so-called lifecycle task in Gradle. The
classes task is actually dependent on two other tasks—compileJava and processResources. We can see this task dependency when we run the tasks command with the command-line option --all:
$ gradle tasks --all ... classes - Assembles the main classes. compileJava - Compiles the main Java source. processResources - Processes the main resources. ...
Let's run the classes task from the command line:
$ gradle classes :compileJava :processResources :classes BUILD SUCCESSFUL Total time: 3.301 secs
Here we can see that the tasks compileJava and processResources are executed, because the classes task depends on these tasks. The compiled class file and properties file are now in the directories build/classes/main and build/resources/main. The build directory is the default directory that Gradle uses to build output files.
If we execute the classes task again, we notice that the tasks support the incremental build feature of Gradle. As we haven't changed the Java source file or the properties file, and the output is still present, all the tasks can be skipped because they are up-to-date:
$ gradle classes :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE BUILD SUCCESSFUL Total time: 2.212 secs
To package our class file and properties file, we invoke the jar task. This task is also added by the Java plugin and depends on the classes task. This means that if we run the jar task, the classes task is also executed. Let's try and run the jar task:
$ gradle jar :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :jar BUILD SUCCESSFUL Total time: 2.401 secs
The default name of the resulting JAR file is the name of our project. So if our project is called sample, then the JAR file is called sample.jar. We can find the file in the build/libs directory. If we look at the contents of the JAR file, we see our compiled class file and the messages.properties file. Also, a manifest file is added automatically by the jar task:
$ jar tvf build/libs/sample.jar 0 Tue Mar 13 09:08:32 CET 2012 META-INF/ 25 Tue Mar 13 09:08:32 CET 2012 META-INF/MANIFEST.MF 0 Tue Mar 13 09:06:50 CET 2012 gradle/ 0 Tue Mar 13 09:06:50 CET 2012 gradle/sample/ 685 Tue Mar 13 09:06:50 CET 2012 gradle/sample/Sample.class 89 Tue Mar 13 07:07:12 CET 2012 gradle/sample/messages.properties
We can also execute the assemble task to create the JAR file. The assemble task, another lifecycle task, is dependent on the jar task and can be extended by other plugins. We could also add dependencies on other tasks that create packages for a project other than just the JAR file, such as a WAR file or ZIP archive file:
$ gradle assemble :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :jar UP-TO-DATE :assemble UP-TO-DATE BUILD SUCCESSFUL Total time: 2.321 secs
To start fresh and clean all the generated output from the previous tasks, we can use the clean task. This task deletes the project build directory and all the generated files in that directory. So if we execute the clean task from the command line, Gradle will delete the build directory:
$ gradle clean :clean BUILD SUCCESSFUL Total time: 2.059 secs
Note that the Java plugin also added some rule-based tasks. One of them was clean<TaskName>. We can use this task to remove the output files of a specific task. The clean task deletes the complete build directory, but with clean<TaskName>, we delete only the files and directories created by the named task. For example, to clean the generated Java class files of the compileJava task, we execute the cleanCompileJava task. Because this is a rule-based task, Gradle will determine that everything after clean must be a valid task in our project. The files and directories created by that task are then determined by Gradle and deleted:
$ gradle cleanCompileJava :cleanCompileJava BUILD SUCCESSFUL Total time: 2.133 secs